Welcome to the Consent Install Guide.
Please note, this guide pertains to the forthcoming version 0.7 of Consent.
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 CONSENTUSER in the environment, for example to ‘consent’.
$ CONSENTUSER=consent
Now, create the Consent system user.
$ sudo adduser $CONSENTUSER --disabled-password
Add the Apache system user to the Consent user group. The Apache system user needs to be able to check for .htaccess files in the wsgi directory.
$ sudo addgroup www-data $CONSENTUSER
Decide which database management system will be used by Consent. 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 Consent 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 Consent 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 Consent, 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/consent-data-dump.json
$ source /path/to/old/consent/bin/activate
$ consent-admin --config /path/to/old/consent/etc/consent.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 Consent 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 Consent will be installed, please check with the Python Package Index.)
$ SITEHOST=$USER.`dnsdomainname`
$ RELEASE=consent-0.7
$ SERVICE=$SITEHOST-$RELEASE
Create a new virtual Python environment and activate it. Then install consent.
To leave room for future versions of Consent software, install Consent to a directory called ‘software’ and a sub-directory named after the version of Consent being installed (RELEASE).
$ virtualenv --no-site-packages $HOME/software/$RELEASE
$ source $HOME/software/$RELEASE/bin/activate
$ pip install consent
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 ‘consent-makeconfig’ and ‘consent-admin’ programs are available.
$ which consent-makeconfig
...
$ which consent-admin
...
The Consent configuration file maker ‘consent-makeconfig’ creates Consent configuration files. There are various options for overiding default values.
The ‘consent-admin setup’ command will set up a Consent service based on the configuration file.
Set and export the Consent environment variable CONSENT_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 Consent (SERVICE).
$ export CONSENT_SETTINGS=$HOME/settings/$SERVICE/consent.conf
You can read about the various options that are supported by the ‘consent-makeconfig’ program.
$ consent-makeconfig --help
Usage: consent-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 Consent 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.
$ consent-makeconfig --master-dir=$HOME/services/$SERVICE \
--service-name="My Consent" --enable-memoization --enable-model-cache \
--site-host=$SITEHOST $CONSENT_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 $CONSENT_SETTINGS
You can read about the various options that are supported by the ‘consent-admin’ program.
$ consent-admin --help
Usage: consent-admin [options] [command]
Administer a Consent service, including its domain objects.
To obtain information about the commands available run the "help" command.
$ consent-admin help
Now, setup a new service based on the configuration file created above. (The ‘consent-admin’ program reads the path to the configuration file from the CONSENT_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).
$ consent-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.
$ consent-admin setup $DUMPPATH
After the service has been setup, make sure the system settings are okay.
$ consent-admin checksettings
You can use the ‘apacheconfig path’ command of the ‘consent-admin’ program to locate the auto-generated Consent Apache configuration file.
$ consent-admin apacheconfig path
It is recommended to run the WSGI process with the process user and group as the Consent system user.
Now, create an Apache virtual host for the new Consent service. It is recommended to create a separate directory for Apache virtual host files.
$ mkdir $HOME/sites
$ echo "<VirtualHost *:80>
ServerName $SITEHOST
Include `consent-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=$CONSENTUSER.`dnsdomainname`
$ sudo ln -s /home/$CONSENTUSER/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 Consent 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 Consent logs for errors. (Set the environment variables, as above, if necessary.)
$ RELEASE=consent-0.7
$ SERVICE=$SITEHOST-$RELEASE
$ sudo tail -f /var/log/apache2/*log
$ sudo tail -f /home/$CONSENTUSER/services/$SERVICE/var/log/consent.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, Consent 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 Consent 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 Consent test suite, then set the Consent configuration option ‘system_mode’ to ‘development’ before setting up the Consent 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 ‘testconsent’ instead of ‘consent’.
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 ‘consent-test’ program.
$ consent-test
The Consent 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 Consent, 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 ‘acceptconsent’ instead of ‘consent’.