Manual installation

Note

This instructions are not up-to-date!

If you really do not want to use the Docker image, they may nevertheless provide enough guidance.

Dependencies

sudo apt install python3 python3-venv rabbitmq-server uwsgi uwsgi-plugin-python3 git texlive-latex-extra texlive-fonts-recommended texlive-lang-german

User

The app should run as an own user, so create one. In this manual the app will be placed in /srv/helfertool, adapt this and the username to your needs.

addgroup --system helfertool
adduser --system --home /srv/helfertool --ingroup helfertool --disabled-password helfertool

Python and app

All following commands should be executed under the user that was created in the last step (here helfertool):

sudo -u helfertool bash

First, create the virtual environment and activate it:

pyvenv .
. ./bin/activate

Now get the source code:

git clone --depth 1 https://github.com/helfertool/helfertool.git

Than install the Python dependencies:

pip install -r helfertool/requirements.txt

Depending on your database choice you have to install further packages:

MariaDB
pip install mysqlclient
PostgreSQL
pip install psycopg2-binary

Basic settings

After the installation of the dependencies it’s time for some basic configuration.

The local configuration has to be places in helfertool/helfertool/settings_local.py, so create this file from the template:

cp helfertool/helfertool/settings_local.dist.py helfertool/helfertool/settings_local.py

Open the file helfertool/helfertool/settings_local.py with your favourite editor. These are the most important settings, that should be set now:

Database

For MariaDB use this configuration:

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.mysql',
        'NAME': 'helfertool',
        'USER': 'helfertool',
        'PASSWORD': '<PASSWORD>',
        'HOST': '127.0.0.1',
        'PORT': '',
        'OPTIONS': {
            "init_command": "SET sql_mode='STRICT_TRANS_TABLES';",
        }
    }
}

For PostgreSQL use this configration:

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'helfertool',
        'USER': 'helfertool',
        'PASSWORD': '<PASSWORD>',
        'HOST': '127.0.0.1',
        'PORT': '5432',
    }
}
RabbitMQ

The connection to RabbitMQ has also to be configured:

CELERY_BROKER_URL = 'amqp://helfertool:<PASSWORD>@localhost:5672/helfertool'
CELERY_RESULT_BACKEND = 'amqp://helfertool:<PASSWORD>@localhost:5672/helfertool'
Secret key

This has to be an unique and secret key.

SECRET_KEY = 'CHANGE-ME-AFTER-INSTALL'

You can generate one with this command:

./helfertool/stuff/bin/gen-secret-key.py
Debug

Set DEBUG to False, you should never deploy a Django app with enabled debugging!

DEBUG = False
Allowed hosts

When debugging is disabled, we need to set the allowed hostnames under which the application is served:

ALLOWED_HOSTS = ['app.helfertool.org', 'www.app.helfertool.org']

Make sure that the file is only readable for the user helfertool since it contains passwords:

chmod 0600 helfertool/helfertool/settings_local.py

Migrations, static files and user creation

To setup the database, the following command has to be executed:

python manage.py migrate
python manage.py createcachetable

The following command collects all static files in one directory that will be delivered by the webserver later:

python manage.py collectstatic

Now we can also create the first user:

python manage.py createsuperuser

Testing

Finally, we can run the development webserver to validate the installation:

python manage.py runserver

Stop the server again with Ctrl + C (it is not suitable for productive deployment).

We can also check the connection to RabbitMQ by starting the some workers:

celery -A helfertool worker -c 2 --loglevel=info

uWSGI

Since the Django part is working now, it’s time to configure the application server uWSGI. The configuration has to be placed in /etc/uwsgi/apps-available, for example in /etc/uwsgi/apps-available/helfertool.ini.

[uwsgi]
plugin          = python35
set-ph          = basedir=/srv/helfertool
chdir           = %(basedir)/helfertool
pythonpath      = %(basedir)/lib/python3.5/site-packages
wsgi-file       = %(basedir)/helfertool/helfertool/wsgi.py
stats           = %(basedir)/uwsgistats.socket
socket          = 127.0.0.1:3001
workers         = 6
touch-reload    = %(basedir)/app_reload
vacuum          = True
uid             = helfertool
gid             = helfertool

smart-attach-daemon = %(basedir)/celery.pid %(basedir)/bin/celery -A helfertool worker -c 2 --pidfile=%(basedir)/celery.pid
exec-as-user-atexit = kill -HUP $(cat %(basedir)/celery.pid)

The file is also part of the git repository in stuff/deployment/uwsgi.conf. Adapt the paths, number of workers and if necessary other settings to your needs.

Then create a symlink in the apps-enabled directory and restart the service:

sudo ln -s /etc/uwsgi/apps-available/helfertool.ini /etc/uwsgi/apps-enabled/helfertool.ini
sudo systemctl restat uwsgi

If you want, you can check for errors in /var/log/uwsgi/app/helfertool.log. Otherwise we will notice possible problems soon.

Reverse proxy

The webserver has to work as reverse proxy in front of uWSGI and also serve the static files. The following section describes the setup with Apache and Nginx, but you could also use tools like HAProxy or Varnish.

Place the configuration in /etc/apache2/sites-available/helfertool.conf, the file is also in the git repository under stuff/deployment/apache.conf.

Place the configuration in /etc/nginx/sites-available/helfertool.conf, the file is also in the git repository under stuff/deployment/nginx.conf.

Review and adapt the settings carefully.