Installation

Development Installation

Vagrant

It's easiest to use the Vagrant VM. For installation instructions using Vagrant, check out the README. This creates a fully working EvaP instance including a database and test data.

You can use EvaP at http://localhost:8000/ on your host (an apache instance is available at http://localhost:8001/), write code in your git repo, and access the VM with vagrant ssh. Your git checkout is mounted in /vagrant there.

Use vagrant halt to shutdown the VM, and vagrant destroy to delete it.

Manual Installation Instructions

On Linux, we recommend that you install the application into the directory /opt/evap according to the filesystem hierarchy standard.

• After cloning the repository, follow the steps in the script used to create the Vagrant VM.
• The apache server is not necessarily needed for development. When using it, make sure that all files and directories are readable by the Apache web server. Additionally please make sure that the directory evap/upload is writable by the web server.
• If you do not want to use the test data, you can use python manage.py createsuperuser to create a user to be able to log in.

Productive Environment

Settings

The configuration of the application is done by creating a localsettings.py in the evap folder and overwriting the defaults from settings.py there. The defaults should be OK for most development purposes. For a production environment you should change the following settings:

• Set the two security-relevant settings DEBUG and SESSION_COOKIE_SECURE:

  DEBUG = False
  SESSION_COOKIE_SECURE = True

• Choose an appropriate database and modify the default entry in the DATABASES settings. Officially, we only support PostgreSQL.
• Change the DEFAULT_FROM_EMAIL to an administrative mail address that is used as the sender of the mails generated by the system.
• Change MEDIA_ROOT to a directory that is writable by the web application. This directory will hold user-uploaded files.
• You should change the SECRET_KEY.

Apache 2 Configuration

See apache.template.conf for an apache config template. The placeholder variables must be changed.

mod_wsgi

The apache2 wsgi module must be installed and enabled. For Debian and Ubuntu, this can be done by installing the libapache2-mod-wsgi-py3 package. You may have to sudo a2enmod wsgi afterwards.

On other systems, you can install the python package mod_wsgi and adding a load script to apache2/mods_available that contains the following LoadModule statement with your matching path: LoadModule wsgi_module /opt/evap/env/lib/python3.7/site-packages/mod_wsgi/server/mod_wsgi-py37.cpython-37m-x86_64-linux-gnu.so

For further details about the Apache and WSGI configuration see

• https://pypi.org/project/mod_wsgi/
• https://modwsgi.readthedocs.io/en/develop/user-guides/virtual-environments.html#daemon-mode-single-application

Updating to a new version

Run update_production.sh as a sudoer.

OpenID Authentication

To use the OIDC authentication backend, the OIDC_RP_CLIENT_* and OIDC_OP_* settings must be set according to your provider.

Database Vacuuming and Clustering

We want to hide insertion order of some tuples (see #1384). For this, old MVCC tuples ("dead tuples") need to be removed. We use a cronjob regularly executing VACUUM. This does not need any further setup, by default, all tables are vacuumed. By running VACUUM first, and then CLUSTER, we don't need to use VACUUM FULL as CLUSTER rewrites the whole table, anyway.

Changes introduced in #1335 rely on postgres regularly clustering a table (https://www.postgresql.org/docs/9.1/sql-cluster.html). The regular re-execution will be set up with a cronjob listed below, but initially, these commands will have to be run once after setting up evap:

# Open psql as user postgres, select database evap
sudo -H -u postgres psql -U postgres -d evap

# List evaluation_ratinganswercounter table details - search for the name of the index on the id
# should look like evaluation_ratinganswercounter_pkey
\d evaluation_ratinganswercounter

# Cluster this table from this index
cluster evaluation_ratingsanswercounter using NAME_OF_ID_INDEX;

# Repeat the same thing for evaluation_textanswer
\d evaluation_textanswer
cluster evaluation_textanswer using NAME_OF_ID_INDEX;

Postgres will remember that these tables were clustered based on these indices and redo the operation when just invoking cluster.

Cron Configuration

EvaP has components which need to react to timed events. This behavior is implemented by running cronjobs, which in turn trigger a management command.

This should run daily:

#!/bin/sh

pushd  <path_to_repository>
sudo -H -u evap /usr/bin/python manage.py send_reminders
sudo -H -u postgres psql -U postgres -d evap -c "vacuum;"
sudo -H -u postgres psql -U postgres -d evap -c "cluster;"
popd

This should run every five minutes:

#!/bin/sh

pushd  <path_to_repository>
sudo -H -u evap /usr/bin/python manage.py update_evaluation_states
popd