Cheetah

Cheetah is the templating system Portfolyo uses to generate HTML output. It is included in the Portfolyo source and installed during a standard install. The performance of this Cheetah version is suboptimal, since it's a pure-Python version. It is highly recommended you download Cheetah yourself and install it separately (with compiled C extensions). Portfolyo will detect an existing Cheetah installation and use it.

Portfolyo has only been tested with Cheetah version 0.9.16a2. Please use that or a higher version.

PIL

Portfolyo will automatically create thumbnails (small preview versions) of pictures attached to projects. To do this the Python Imaging Library (PIL) is required. Install PIL if you want thumbnails.

Database tables

First create the database tables. You can find the SQL statements needed for that in the file db/create_tables_mysql.sql for MySQL or in db/create_tables_postgresql.sql for PostgreSQL. Execute the contents of this file on your database. How exactly that is done is hard to predict without knowning the specifics of your system.

If you have some kind of web-based admin interface available (e.g. phpMyAdmin or phpPgAdmin), use that. If you happen to be able to connect to your database server from your local machine, you can feed the file directly to the command line client. Using MySQL:

mysql -u user -h host -p database < db/create_tables_mysql.sql

Using PostgreSQL:

psql -U user -h host -f db/create_tables_postgresql.sql database

Installing files

You must copy three types of files to your web server: CGI scripts, library files and template files. You should also create a picture directory.

• The CGI scripts are in the directory cgi-bin of a Portfolyo release. Copy the files in there to the directory on your server, where you want them to be accessed via the web. It should be a directory in which your web server can execute CGI Python scripts.

  If you're web server is Apache, you'll most probably have to make sure that the shebang lines of these files point to your Python interpreter. For example, if the Python interpeter on your server is at /usr/local/bin/python change the first line of all CGI scripts (except for the config file pfconfig.cgi) to this:

  #!/usr/local/bin/python
  

  Then set the correct (execute) permissions on the CGI files. On a Unix-ish system you might do that like this:

  chmod 755 *.cgi
  

• The library files are in the directory portfolyo of a Portfolyo release. If you have the privileges to do so, copy this directory to the site-packages directory of the Python installation on your server.

  If you can't do this or don't know where your site-packages directory is, you can also copy the library directory to the CGI directory you installed the CGI scripts to. For example, if you installed the CGI scripts to the directory cgi-bin on your web server, copy all files in the portfolyo directory of your release to the directory cgi-bin/portfolyo.

• The template files are in the directory templates of a Portfolyo release. Copy this directory to a location of your choice on the web server. Just make sure that it's some place where the CGI scripts can access them.

  It's recommended to install them in the same directory you put the CGI scripts. For example, if you installed the CGI scripts to the directory cgi-bin on your web server, copy all files in the templates directory of your release to the directory cgi-bin/templates.

  Preferrably the directories below the templates are world-writeable, so the CGI scripts can compile templates in them. Here's how you'd assert this on a Unix-ish system, assuming you've copied the templates to the directory /var/www/cgi-bin/templates on your server. In a terminal type this:

  cd /var/www/cgi-bin/templates
  chmod 777 *
  

• The picture directory is used to store pictures and binary files uploaded through the administration interface. It's most convenient to elect a subdirectory of the CGI directory as picture directory. Simply create a directory and make it world-writeable. On a Unix-ish system you'd do:

  mkdir pictures
  chmod 777 pictures
  

As an example, this is a typical directory layout after you copied all files to your web server:

public_html/                       (web server root)
    cgi-bin/                       (CGI scripts)
         pictures/                 (picture directory)
         portfolyo/                (library files)
         templates/                (template files)

Configuration

Everything else in place, you should now update your config file. You will have to change at least the database parameters, the templatePath, the picturePath and the adminPwd. The default config file is sprinkled with comments explaining the parameters, so you should be able to figure out what values to use. For a more in-depth discussion see the section Configuration parameters.

When the installer fails

If the installer was successful, it will report back with a message along the lines of "Successfully installed Portfolyo". If you don't see the success message after the installer finished, it must have encountered a problem during installation.

Here are some things you can check when the installer fails:

• Are you using the correct Python version? You need Python 2.2 or greater. Type "python -V" in your shell to display your Python's version number.

• Are you specifying valid database parameters? If the installer issued a Python stack trace and it seems to be about MySQL/PostgreSQL, there is most likely a problem with the database parameters you passed to the installer. Using MySQL, the last line of the stack trace will look like this in most of those cases:

  _mysql_exceptions.OperationalError: (1045, "Access denied for user:
  'someuser@localhost' (Using password: YES)")
  

  Using PostgreSQL, you will probably get a similarly looking OperationalError.

  Verify that the database you specified exists, and that the user you specified does have privileges on this database. The user especially needs privileges to create tables on this database. Also verify that you correctly typed the password of the user. Then run the installer again.

• Do you have write permissions on all installation directories? You need write permissions on the directories you passed as cgidir, templatedir and libdir to the installer. If you don't, you'll normally see this as the last line of output from the installer:

  error: could not create '/usr/lib/python2.2/site-packages/portfolyo': Permission denied
  

  Most problems happen with libdir. If you don't specify a libdir, the installer will try to install libraries into the site-packages directory of your Python installation. Normally, only administrators have access to this directory. If you didn't specify a libdir and the installer failed with the above error message, log in to your system as an administrator (i.e. use sudo on Unix-ish systems) to run the installer - if you can. If you can't, install the libraries somewhere else. It's recommended to specify the same directory for libdir as for cgidir in that case.

• Are your distutils broken? The Portfolyo installer uses the Python standard module distutils to do part of its work. If the installer issued a Python stack trace which mentions distutils, the module is most likely not present or broken. Some Linux distributions do not bundle distutils with their standard Python package. Check if there's something like a python-devel package for your distribution and install that. If this doesn't apply to you or doesn't help, you should try a Manual installation.

If you think you're experiencing a problem not described above, contact us at portfolyo@ubique.ch. Don't forget to include the output of the installer and information about your system (operating system, Python version number and other stuff relevant to your problem) in your email.

When the CGI scripts fail

The first thing you should do when you think the CGI scripts portfolyo.cgi or pfadmin.cgi are not working when viewed in a browser, is turn on debug mode. You do this by setting the debug parameter in the config file pfconfig.cgi to "1".

Having turned on debug mode, hit the failing CGI script again. What do you see in your browser, now? Three common cases are covered below.

• You get a "500 Internal Server Error". This means there is a problem not in the script itself, but in the CGI environment it's being executed in. Two situations are common:

  • The CGI scripts don't have execute permission. Verify that the scripts can be executed. On a Unix-ish system you can ensure this by typing issuing the chmod command in a shell in the CGI directory:

    chmod 755 *.cgi
    

  • Using Apache, the shebang line of the CGI scripts doesn't point to a Python interpreter. For example, if the Python interpreter on your server is at /usr/bin/python the first line of the CGI scripts - the so-called "shebang" - must look like this:

    #!/usr/bin/python
    

• You see a Python stack trace. This means the script was handed over to the Python interpreter, but there was an error during execution. If you're familiar in any way with Python, you should be able to figure out what caused the error. If reading stack traces is not your thing, here's some things that could have gone wrong:

  • You specified invalid database parameters in the config file. Verify that the database specified in the config file pfconfig.cgi exists and that the specified user does have read privileges on this database. Also verify that the password is correct.
  • The Portfolyo libraries are not on your Python path. This is probably true if you see an ImportError in the stack trace. Verify that the libraries are either installed in the standard site-packages directory of your Python installation or in a directory called portfolyo in the CGI directory.
  • You're using an outdated Python version. Verify that you have Python 2.2 or greater. Type "python -V" in a shell to display your Python's version number.

• The code of the script is shown in plain text. This means your web server doesn't interpret the file as a CGI script. You have to tell it to - consult the documentation of your web server on how this is done. If you're using Apache, you'd normally do it by creating a text file named .htaccess with these contents:

  Options +ExecCGI
  AddHandler cgi-script .cgi
  

  Copy this file to the directory of your CGI scripts and see if this fixes the problem.

Don't forget to turn off debug mode, as soon as you have solved your problem. Leaving it on won't hurt you directly, but it's considered safer to turn it off when the general public is browsing around your portfolio.

If you think you're experiencing a problem not described above, contact us at portfolyo@ubique.ch. Don't forget to include the text seen in your browser (maybe you can even provide a link to the CGI script) and information about your system (operating system, web server, Python version number and other stuff relevant to your problem) in your email.

Upgrading from 0.1

Versions after 0.1 have template compiling turned on by default. Template compiling works only, if the CGI scripts have write access to the template directories. Usually this means, these directories need to be world-writeable. The installer cannot manage these access rights, so you should do that yourself after an upgrade from Portfolyo 0.1.

Here's how you'd do it on a Unix-ish system, assuming your template sets are in the directory /var/www/cgi-bin/templates. In a terminal type this:

cd /var/www/cgi-bin/templates
chmod 777 *

If you can't or don't want to take care of this, you can also simply turn off template compiling by adding the compileTemplates parameter to your config file:

compileTemplates = 0

Upgrading to 0.2 or higher

Starting from version 0.2 the database schema changes slightly with almost every release. The installer will migrate your existing data to the new schema - but only if the existing version you're using is 0.1.3 or higher. If you want to upgrade to 0.2 (or higher) from a version lower than 0.1.3, please upgrade to 0.1.3 first.

Version 0.2 introduced the configuration parameter picturePath. You have to add this manually to your configuration file after the upgrade. If you haven't specified anything else while executing the installer, it has created a subdirectory of your CGI directory called pictures. So normally you can simply add this line to your configuration file:

picturePath = pictures