Welcome to the Desire Install Guide.
Please note, this guide pertains to the forthcoming version 0.37 of Desire.
Using an account that has root privileges, install the following system packages (Debian package names).
$ sudo aptitude install python-virtualenv virtualenvwrapper apache2 \
apache2-mpm-worker libc-bin libapache2-mod-wsgi build-essential \
python-dev locales hostname
Make sure the following Apache modules are enabled.
$ sudo a2enmod wsgi env alias
If you would like to copy and paste the bash shell commands below, please set DESIREUSER in the environment, for example to ‘desire’.
$ DESIREUSER=desire
Now, create the Desire system user.
$ sudo adduser $DESIREUSER --disabled-password
Add the Apache system user to the Desire user group. The Apache system user needs to be able to check for .htaccess files in the wsgi directory.
$ sudo addgroup www-data $DESIREUSER
Decide which database management system will be used by Desire. The choices are SQLite (default), PostgreSQL, and MySQL.
If you want to use PostreSQL or MySQL, then follow the sections below. If you want to use SQLite, there is no need to anything further to prepare the database.
If you want to use PostgreSQL, then install the PostgreSQL packages (pick the version of the -dev- package according to the version of PostgreSQL on your system).
$ sudo aptitude install postgresql postgresql-server-dev-X.X
Make sure the Desire system user can access the database via TCP/IP sockets with a password. If necessary, please refer to the PostgreSQL manual.
Remember the database username and password, and the name of the new database.
If you want to use MySQL, then install the MySQL packages.
$ sudo aptitude install mysql-server libmysqlclient-dev
Make sure the Desire system user can access the database via TCP/IP sockets with a password. If necessary, please refer to the MySQL manual.
Remember the database username and password, and the name of the database.
If you are migrating from an older version of Desire, then prepare the migration data file by activating the old vitualenv and dumping the old data. Before dumping the data, set the path to the dump file in the environment, so the path can be reused when setting up the new service (below).
$ DUMPPATH=$HOME/desire-data-dump.json
$ source /path/to/old/desire/bin/activate
$ desire-admin --config /path/to/old/desire/etc/desire.conf migratedump $DUMPPATH
$ deactivate
If you would like to copy and paste the bash shell commands below, then set the following environment variables: SITEHOST as the fully qualified domain name of your Desire site; RELEASE as the name of the release; and SERVICE as a combination of SITEHOST and RELEASE
(If you don’t know which version of Desire will be installed, please check with the Python Package Index.)
$ SITEHOST=$USER.`dnsdomainname`
$ RELEASE=desire-0.37
$ SERVICE=$SITEHOST-$RELEASE
Create a new virtual Python environment and activate it. Then install desire.
To leave room for future versions of Desire software, install Desire to a directory called ‘software’ and a sub-directory named after the version of Desire being installed (RELEASE).
$ virtualenv --no-site-packages $HOME/software/$RELEASE
$ source $HOME/software/$RELEASE/bin/activate
$ pip install desire
If you are going to use PostreSQL, then also install its Python adapter.
$ pip install psycopg2
If you are going to use MySQL, then also install its Python adapter.
$ pip install MySQL-python
Check the ‘desire-makeconfig’ and ‘desire-admin’ programs are available.
$ which desire-makeconfig
...
$ which desire-admin
...
The Desire configuration file maker ‘desire-makeconfig’ creates Desire configuration files. There are various options for overiding default values.
The ‘desire-admin setup’ command will set up a Desire service based on the configuration file.
Set and export the Desire environment variable DESIRE_SETTINGS as the filesystem path for the new configuration file.
It is recommended to keep the configuration file in a directory called ‘settings’, and a sub-directory named after both the site host and the new version of Desire (SERVICE).
$ export DESIRE_SETTINGS=$HOME/settings/$SERVICE/desire.conf
You can read about the various options that are supported by the ‘desire-makeconfig’ program.
$ desire-makeconfig --help
Usage: desire-makeconfig [OPTIONS] [PATH]
Generate new configuration file, see --help for options.
Writes file to PATH if given, otherwise prints to stdout.
...
To leave room for future services (setup from future releases of Desire software), it is recommended to use the ‘–master-dir’ option, so the service will be setup within a directory called ‘services’, and a sub-directory named after both the site host and the version of Kforge (SERVICE).
You may also wish to set the service name for your service by using the ‘–service-name’ option, so that your site can be recognised by users.
You may also wish to enable memoisation (‘–enable-memoization’) and the model cache (‘–enable-model-cache’).
It is also recommended to set the site host, by using the ‘–site-host’ option, so that for example email messages can correctly link back to the site.
And if you are using PostreSQL or MySQL, then you will need to use the ‘–db-type’, ‘–db-name’, ‘–db-user’ and ‘–db-pass’ options. (Otherwise, if you are using SQLite, then you do not need to use these options. But if you wish to specify the location of the SQLite file, then you can use the ‘–db-type’ to provide a filesystem path.)
Now, create the configuration file.
$ desire-makeconfig --master-dir=$HOME/services/$SERVICE \
--service-name="My Desire" --enable-memoization --enable-model-cache \
--site-host=$SITEHOST $DESIRE_SETTINGS
Edit the new configuration file, and review the options. If you are upgrading from an existing service, then copy and paste any preferences for timezone, password digest secret, SMTP settings, and so on.
$ editor $DESIRE_SETTINGS
You can read about the various options that are supported by the ‘desire-admin’ program.
$ desire-admin --help
Usage: desire-admin [options] [command]
Administer a Desire service, including its domain objects.
To obtain information about the commands available run the "help" command.
$ desire-admin help
Now, setup a new service based on the configuration file created above. (The ‘desire-admin’ program reads the path to the configuration file from the DESIRE_SETTTINGS environment variable.) If something goes wrong, you will need to move or remove the directories created under the “master directory” before trying again (and recreate an empty database if using PostgreSQL or MySQL).
$ desire-admin setup
If you are upgrading, you can provide the path to the migration data as an additonal argument to the ‘setup’ command. This will initialise the database with migrated data, rather than default data.
$ desire-admin setup $DUMPPATH
After the service has been setup, make sure the system settings are okay.
$ desire-admin checksettings
You can use the ‘apacheconfig path’ command of the ‘desire-admin’ program to locate the auto-generated Desire Apache configuration file.
$ desire-admin apacheconfig path
It is recommended to run the WSGI process with the process user and group as the Desire system user.
Now, create an Apache virtual host for the new Desire service. It is recommended to create a separate directory for Apache virtual host files.
$ mkdir $HOME/sites
$ echo "<VirtualHost *:80>
ServerName $SITEHOST
Include `desire-admin apacheconfig path`
WSGIDaemonProcess $SITEHOST user=$USER group=$USER threads=15 maximum-requests=10000
</VirtualHost>
" > sites/$SITEHOST
Exit the shell, return to the account that has root priveleges. Link to the Apache virtual host. Enable the Apache virtual host and restart Apache.
$ exit
$ SITEHOST=$DESIREUSER.`dnsdomainname`
$ sudo ln -s /home/$DESIREUSER/sites/$SITEHOST /etc/apache2/sites-available/$SITEHOST
$ sudo a2ensite $SITEHOST
$ sudo /etc/init.d/apache2 restart
Configure your DNS so the site name can be resolved (or as a temporary fix, set the site host in your hosts file).
Check you can resolve the site name.
$ getent hosts $SITEHOST
...
Now, visit the Desire service in a browser.
$ www-browser http://$SITEHOST
For a new service, login with username ‘admin’, password ‘pass’. Please note, it is strongly recommended that you update this password immediately. If you are migrating, then login with previously established credentials.
Optionally, tail the Apache and Desire logs for errors. (Set the environment variables, as above, if necessary.)
$ RELEASE=desire-0.7
$ SERVICE=$SITEHOST-$RELEASE
$ sudo tail -f /var/log/apache2/*log
$ sudo tail -f /home/$DESIREUSER/services/$SERVICE/var/log/desire.log
Configure a cronjob to dump the domain data, and then rsync all files to a remote machine.
Then, you will be able to restore the site by following the instructions for migrating. You may wish to test that your backup is working by building and maintaining a “fail-over” site on a different machine.
Please note, Desire should not be installed under DocumentRoot of the Apache installation, or any other directory exposed via Apache web server.
It is recommended to run a production service with PostgreSQL. You may also wish to enable both model cacheing and access control memoisation (see Desire configuration file). You may also wish to adjust Apache MPM parameters and the WSGI process parameters to match your hardware.
Please note, a production service should be created freshly and not by reusing a service that has been used to run the test suite. Do not run the test suite against a production service.
If you wish to run the Desire test suite, then set the Desire configuration option ‘system_mode’ to ‘development’ before setting up the Desire service. Do not enable model cacheing, and do not enable access control memoisation.
It is recommended to repeat the above steps, starting from ‘Create System User’ perhaps with a system user name of ‘testdesire’ instead of ‘desire’.
The reason for creating a new user for each site is to make sure SSH access for each service is well separated (there can only be one authorized_users file per system user).
Now, the test suite can be executed by running the ‘desire-test’ program.
$ desire-test
The Desire software, and this install guide, have been tested with Python 2.6 on Debian 6, and with Python 2.7 on Ubuntu 12.10.
If you wish to create a user acceptance testing site for a new version of Desire, whilst leaving the current production service in operation, then repeat the above steps, Starting from ‘Create System User’ perhaps with a system user name of ‘acceptdesire’ instead of ‘desire’.