Installation

Development Installation

Vagrant

Usually it's easiest to just 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 (Linux)

We recommend that you install the application into the directory /opt/evap according to the filesystem hierarchy standard. In the remaining steps, we will assume that this is your installation directory.

• After cloning the repository, follow the steps in the script used to create the Vagrant VM.
• The apache server is not 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 /opt/evap/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.

Manual Installation Instructions (Windows)

Note that you still need to setup the Vagrant VM, since redis is not available for Windows. Alternatively, you can change the settings to use a different (and most likely slower) caching backend.

• pip install --user rcssmin==1.0.6 --install-option="--without-c-extensions"
• pip install --user rjsmin==1.0.12 --install-option="--without-c-extensions"
• pip install --user -r .\requirements-dev.txt
• download sassc (direct link), rename the .exe to sass.exe, put it somewhere on the PATH (e.g. into C:\Windows\System32)
• download postgres, install it. enter evap as password
• run "C:\PostgreSQL\pg10\bin\createuser.exe" -U postgres --createdb evap
  • enter evap as password
• run this: "C:\PostgreSQL\pg10\bin\psql.exe" -U postgres -d postgres -c "ALTER USER evap WITH PASSWORD 'evap';"
  • enter evap as password
• run vagrant ssh, sudo vim /etc/redis/redis.conf and add this line: bind 0.0.0.0
• run python manage.py reload_testdata

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:

• Choose an appropriate database and modify the default entry in the DATABASES settings. Please make sure that you use a database that supports transactions.
• 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.
• Finally, set DEBUG to False.

Virtual Environment

To be able to use a custom python version independent from the versions available for your operating system by default, you should create a virtual environment and use it for running the django application:

1. Add the "deadsnakes" repository to your package manager:
   sudo add-apt-repository ppa:deadsnakes/ppa
2. Update the list of available packages:
   sudo apt-get update
3. Install the python version of choice (here: 3.7) and the dev-packages for python and Apache:
   sudo apt-get install python3.7 python3.7-dev apache2-dev

Do the following as the user who is running the application (e.g., "evap"):

4. Change to the application's location:
   cd /opt/evap
5. Create a virtual environment called "env":
   python3.7 -m venv env
6. In this virtual environment install mod_wsgi:
   env/bin/pip install mod_wsgi

Apache 2 Configuration

See apache.template.conf for an example apache config. You should change the WSGI settings from the example like so:

WSGIScriptAlias / /opt/evap/evap/wsgi.py
WSGIDaemonProcess evap processes=2 threads=15 display-name=%{GROUP} user=evap python-home=/opt/evap/env
WSGIProcessGroup evap

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.

Kerberos Authentication

To use Kerberos as an authentication backend, do the following:

• run env/bin/pip install django-auth-kerberos

• copy the following to your localsettings.py and edit KRB5_REALM and KRB5_SERVICE according to your setup:

KRB5_REALM = 'EXAMPLE.COM'
KRB5_SERVICE = 'krbtgt@AS.EXAMPLE.COM'
INSTALLED_APPS += ('django_auth_kerberos',)
MIDDLEWARE_CLASSES += ('django_auth_kerberos.backends.KrbBackend',)

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