Installing peach³

Setting up the environment

peach³ is built upon Django, a high-level Python based Web framework. Besides Django, peach³ has several other depencencies.

To manage the depencencies we provide a buildout.cfg script for use with zc.buildout. This installation manual assumes that you use that buildout configuration to set up the peach³ environment. The buildout environment is set up inside a virtual python environment created with virtualenv.

To set up the peach³ environment, Python (at least version 2.5, but version 2.6 is preferred, version 3 and up are not supported yet) and virtualenv should be available on the system. You will also need a working MySQL database and ImageMagick installed. Installing Memcached is recommended as peach³ relies heavily on caching to speed up lookups.

There is no special requirement on where to install peach³. There are several “standard” locations:

  • A subdirectory in /opt,
  • A subdirectory somewhere in /usr/local,
  • Creating a special user and installing in the user’s home directory.

Which option you choose depends on your system and on your preference.

For the rest of this document we assume you have created a user peachwww and will be installing peach³ in /home/peachwww.

Go to the directory where you want to install peach³ and untar or copy the contents of the tar to this directory. This should create a directory called peach3-django-{version}. Rename this directory to peach3-django and convert it into a virtual python environment:

virtualenv --no-site-packages peach3-django

This will add a bin directory containing the python executable and a script to activate the virtual environment.

Enter the peach3-django directory and activate the virtual environment with:

cd peach3-django
source bin/activate

By activating a virtual environment, all python packages will now be installed inside the virtual environment. To deactivate a virtual environment use the command deactivate. But don’t deactivate the environment just yet.

The buildout configuration requires a “bootstrapping” procedure. To initialise the buildout environment enter the following:

cd django
python ./bootstrap.py

This will create a new directory bin in the django directory and generate a script called buildout. This buildout script is the script that will install all peach³ depencies. To initiate the buildout, start the buildout script:

bin/buildout

Normally buildout will download all dependencies, but in the tar distribution, all peach³-dependencies are already available.

Besides installing all dependencies, buildout will also create a new script in the bin directory called django. This django script is the entry-point into peach³. This script replaces the standard Django manage.py script.

Setting up ExtJS

peach³ uses ExtJs, a javascript application framework, for the client-side user interface. The current beta3 version of peach³ requires ExtJS version 2.2.1 and will not work with any older or newer version. You can find this version of ExtJS in the deps directory.

Unzip extjs-2.2.1.zip, for example in peachwww/web-toolkits/.

PDF viewer depencies

peach³ includes a PDF rendering component that will convert PDF files into images.

This rendering component requires the convert command from ImageMagick to be available in the default PATH. Currently ImageMagick must be installed globally on your system, we do not (yet) have a way to install it in the virtual environment, nor is there an option to disable the PDF to image conversion.

Configuring peach³

peach³ is a Django project, and uses the standard Django settings.py file for configuration.

See the “Django settings” section of the Django documentation on how to manage the settings.

The settings file can be found in peach3-django/django/peach3/settings.py.

The following standard Django settings should at least be modified to match your site:

  • ADMINS
  • All CACHE_* fields
  • All DATABASE_* fields (more about setting up these later)
  • SECRET_KEY [1]
  • TIME_ZONE

For a description of these and other Django settings, see the “Available settings” section of the Django documentation.

[1]For security reasons, each Django installation requires a unique SECRET_KEY. The peach³ buildout.cfg installs the django-extensions package, which allows you to easily generate a new secret key for your installation. Running peach3-django/django/bin/django generate_secret_key will print a new secret key you can copy/paste into settings.py.

peach³ settings

Besides the standard Django configuration, peach³ has it’s own settings in settings.py. In this section we’ll only discuss the peach³ specific settings.

STORE

The location where peach³ should store the files. Unlike all other data in peach³ which is stored in a database, all files (user submissions etc.) are stored in the file system in this location. Make sure no unauthorized users can access this directory.

Example: '/home/peachwww/store'

TEMP

The location where peach³ can safely store temporary files, eg. generated reports. Like the STORE, this location should not be accessible by unauthorized users.

Example: '/home/peachwww/temp'

PDF_VIEWER_THREADS

Maximum number of background threads the PDF-to-image generator may use.

Example: 2

PDF_VIEWER_CACHE

The location where the PDF-to-image generator will store the generated images.

Example: 'home/peachwww/store/pdf_cache'

BASE_URL

The “home” location of peach on the web.

Example: 'http://peach.win.tue.nl/'

ANALYTICS_ID

peach³ will incorporate a Google Analytics javascript section if this setting is set to a string. Set to None to disable.

Example: 'UA-12345-1'

MEDIA_URL

The url (relative to BASE_URL, or absolute) where peach³ media (like images, stylesheets and static javascript) is hosted.

Examples:

  • '/media/'
  • 'http://peachstatic.win.tue.nl/'

MEDIA_SSLURL

The relative url where peach³ media (like images, stylesheets and static javascript) is hosted for secure sessions. If using a relative location (in the same domain as BASE_URL), this should be the same as MEDIA_URL.

Example: '/media/'

MEDIA_ROOT

The location on the filesystem where the peach³ static media is located.

Example: '/home/peachwww/media'

EXTJS_DEBUG

Set to True to enable debugging of Javascript. When set to True, the debug version of ext.js is loaded. Set to False on a production server.

Example: False

EXTJS_URL

The url where the ext.js library is located.

Example: '/extjs/'

EXTJS_SSLURL

The url where the ext.js library is located for secure sessions.

Example: '/extjs/'

EXTJS_ROOT

The location on the filesystem where the ext.js library is located.

Example: '/home/peachwww/web-toolkits/extjs-2.2.1/'

REGISTRATION_NAME_FIELDS

Indicates which fields to show on the user registration form.

The possible fields are:

  • titles_prefix
  • first_name
  • last_name_prefix
  • last_name
  • last_name_suffix
  • titles_suffix
  • initials

The REGISTRATION_NAME_FIELDS setting is a Python list. This list contains a tuple for each field to include on the registration form. This tuple can consist of 2 or 3 fields:

  • The first field is the name of the field, one of the possible names listed above.
  • The second field is a boolean True or False indicating whether that field is required (may not be empty) upon registration.
  • The third (optional) field is a list of predefined values. If this field exists, the form field is rendered as a combobox with the listed values. The user can also enter another value.

Example:

REGISTRATION_NAME_FIELDS = [
  ('first_name', False),
  ('last_name_prefix', False, [
    '', 'de', 'van', 'van de', 'van der',
  ]),
  ('last_name', True),
  ('initials', False),
]

PEACH3_JS_FILE

The name of the peach3.js javascript file.

Example: 'peach3.js'

RST_EXTENSIONS

Extensions for the rST parser used in peach³. It should not be necessary to modify this setting.

Setting up a database

While Django supports several database backends, peach³ has currently only been tested with MySQL.

How to set up Django with a MySQL database is described in the MySQL database section of the Django documentation.

After setting up MySQL and configuring the database in settings.py, the database tables need to be created.

Because peach³ uses django-south, a Django tool that helps with database migration, setting up the database differs somewhat from the default Django way.

First, the normal Django syncdb needs to be run:

cd /home/peachwww/peach3-django/django
bin/django syncdb

This will create the database tables that are not controlled by django-south. It will also ask you to create an administrator account.

Next, the database tables that are managed by django-south need to be created:

bin/django migrate

Testing peach³

After these steps, the database is ready. You can now easily test the installation using the Django development webserver using the following command:

cd /home/peachwww/peach3-django/django
bin/django runserver

This will start the Django development webserver on port 8000. It will only respond to requests from localhost. See the Django documentation about the runserver command for more details.

The development webserver is fine to testing, but it cannot be used for normal operation.

Deploying peach³

Since peach³ is a standard Django project, deploying peach³ is no different than deploying any other Django project. See the Django documentation section on how to install Django.

As an example of how to deploy peach³ we’ll include the configuration used for the http://demo.peach3.nl/ server.

peach³ itself is started as a seperate process. A /etc/init.d script takes care of starting peach³.

/etc/init.d/fcgi-w3p3demo:

#!/sbin/runscript

BASEDIR=/home/w3p3demo

depend() {
  need net
  use dns
}

start() {
  ebegin "Starting FCGI server w3p3demo"

  start-stop-daemon --start --quiet \
                    --chuid w3p3demo:apache --nicelevel 10 \
                    --pidfile $BASEDIR/run/fcgi-w3p3demo.pid \
                    -e PYTHON_EGG_CACHE=$BASEDIR/tmp/.python-eggs \
                    --exec $BASEDIR/peach3-django/django/bin/django -- runfcgi \
                    --settings=peach3.settings_w3p3demo \
                    daemonize=true \
                    method=threaded \
                    minspare=1 \
                    maxspare=3 \
                    workdir=$BASEDIR/peach3-django/django \
                    socket=$BASEDIR/run/fcgi-w3p3demo.sock umask=007 \
                    pidfile=$BASEDIR/run/fcgi-w3p3demo.pid \
                    outlog=$BASEDIR/log/fcgi-w3p3demo-stdout.log \
                    errlog=$BASEDIR/log/fcgi-w3p3demo-stderr.log

  eend $? "Failed to start FCGI server w3p3demo"
}

stop() {
  ebegin "Stopping FCGI server w3p3demo"
  start-stop-daemon --stop --quiet --pidfile $BASEDIR/run/fcgi-w3p3demo.pid
  eend $? "Failed to stop FCGI server w3p3demo"
}

This init script will start a FCGI Django process using the runfcgi command of django-extensions. The configuration for this server is in peach3/settings_w3p3demo.py

Apache is configured to forward requests to this FCGI server:

(part of) /etc/apache/vhost.d/demo.peach3.nl:

<VirtualHost *:80>
  ServerName demo.peach3.nl

  DocumentRoot "/home/w3p3demo/htdocs/"

  ErrorLog /home/w3p3demo/log/error_log
  LogFormat "%V %h %l %u %t \"%r\" %s %b" vcommon
  CustomLog /home/w3p3demo/log/access_log vcommon
  CustomLog /home/w3p3demo/log/referer_log referer

  FastCgiExternalServer /home/w3p3demo/htdocs/w3p3demo.fcgi -socket /home/w3p3demo/run/fcgi-w3p3demo.sock -idle-timeout 60

  <Directory "/home/w3p3demo/htdocs/">
    Options Includes FollowSymLinks
    AllowOverride All
    Order allow,deny
    Allow from all
  </Directory>

  RewriteEngine On
  RewriteRule /\.svn/             -                 [F]
  RewriteRule ^/(media/.\*)$       /$1               [PT,QSA,L]
  RewriteRule ^/(admin/media/.*)$ /$1               [PT,QSA,L]
  RewriteRule ^/(ext/.\*)$         /$1               [PT,QSA,L]
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteRule ^/(.*)$             /w3p3demo.fcgi/$1 [PT,QSA,L]

  ErrorDocument 500 /offline.html
</VirtualHost>

This configuration will serve files in /media/, /admin/media/, /ext/ using Apache, and all other requests will be sent to the peach³ FCGI process.

Apache will look for the static files in /home/w3p3demo/htdocs. This directory contains softlinks to the real location where the media files are located:

# ls -lR htdocs

htdocs:
total 40
drwxr-xr-x 2 w3p3demo apache    18 Apr  3  2009 admin
drwxr-xr-x 2 w3p3demo apache   102 Apr  7  2009 ext
-rw-r--r-- 1 w3p3demo apache 25214 Apr  3  2009 favicon.ico

htdocs/admin:
total 0
lrwxrwxrwx 1 root root 60 Apr  3  2009 media -> ../../peach3-django/django/parts/django/django/contrib/admin/media

htdocs/ext:
total 0
lrwxrwxrwx 1 root root 24 Apr  3  2009 adapter -> ../../web-toolkits/ext/adapter
lrwxrwxrwx 1 root root 33 Apr  3  2009 ext-all-debug.js -> ../../web-toolkits/ext/ext-all-debug.js
lrwxrwxrwx 1 root root 27 Apr  3  2009 ext-all.js -> ../../web-toolkits/ext/ext-all.js
lrwxrwxrwx 1 root root 30 Apr  3  2009 locale -> ../../web-toolkits/ext/source/locale
lrwxrwxrwx 1 root root 26 Apr  3  2009 resources -> ../../web-toolkits/ext/resources
lrwxrwxrwx 1 root root 24 Apr  7  2009 source -> ../../web-toolkits/ext/source/

Regular cleanup (cron job)

While handling requests, peach³ generates temporary files to cache calculation intensive operations like generated reports and PDF-file images. These caches must be cleaned at regular intervals.

To remove old temporary files, run the command peach3-django/django/bin/django cleanup regulary, eg. every 10 minutes. This is best done from a cron job.