This installation guide is written for Debian Bullseye.

Docker and helfertoolctl

First, install Docker according to the Docker documentation.

The helfertoolctl package can be installed from the Debian repository

sudo apt install gnupg

echo "deb bullseye main" | sudo tee /etc/apt/sources.list.d/helfertool.list

sudo apt-key adv --recv-keys FA1023F9F6AC494F

sudo apt update
sudo apt install helfertoolctl

The available Debian and CentOS repositories are listed in the section about helfertoolctl.


PostgreSQL is the recommended database for Helfertool deployments.


sudo apt install postgresql

Then create an user and database:

sudo -u postgres createuser -P helfertool
sudo -u postgres createdb -O helfertool helfertool

The Helfertool supports similarity based search, which requires the extension pg_trgm. You can enable the extension already, but it is not required:

sudo -u postgres psql helfertool


By default, PostgreSQL only listens to localhost. To allow access from the Docker container, the following configuration files need to be modified:

listen_addresses = '*'
# connection from docker container
host    all             all              md5

Then restart PostgreSQL:

sudo systemctl restart postgresql


sudo apt install mariadb-server

Then create an user and database:

sudo mysql
MariaDB [(none)]> CREATE DATABASE helfertool;
MariaDB [(none)]> CREATE USER helfertool IDENTIFIED BY '<PASSWORD>';
MariaDB [(none)]> GRANT ALL PRIVILEGES ON helfertool.* TO helfertool;
MariaDB [(none)]> ALTER DATABASE helfertool CHARACTER SET utf8;

You probably have to load the time zone tables into the database, otherwise you will see some strange Django errors:

mysql_tzinfo_to_sql /usr/share/zoneinfo | sudo mysql -u root mysql
sudo systemctl restart mysql


sudo apt install rabbitmq-server

A new user and virtualhost should be created in RabbitMQ, additionally the default user guest should be deleted for security reasons.

sudo rabbitmqctl add_user helfertool <PASSWORD>
sudo rabbitmqctl add_vhost helfertool
sudo rabbitmqctl set_permissions -p helfertool helfertool '.*' '.*' '.*'
sudo rabbitmqctl delete_user guest

Choose version and container download

By default, the latest tag is used (see versions and tags).

If you want to, the used Docker tag can be changed in /etc/default/helfertool, for example:


Then download the Helfertool container:

sudo helfertoolctl download

Basic configuration

Now edit the configuration file /etc/helfertool/helfertool.yaml and configure at least the following settings:

  • Database

  • RabbitMQ

  • Mail server

  • Secret key (security > secret)

  • Allowed hosts (security > allowed_hosts)

Details about the configuration file can be found here.

First start

Now is is time for the first start of the Helfertool, we should also enable the autostart here:

sudo systemctl enable --now helfertool

To check the progress, you can use journalctl:

sudo journalctl -f -u helfertool

On the first start, the database migration are applied and after that the container is running and listens on port 8000 (on localhost only by default). Due to the set headers, the Helfertool is not usable without TLS, so the reverse proxy needs to be configured.

Reverse proxy

The webserver works as reverse proxy in front of the Docker container and terminates the TLS connection. The following section describes the setup with Apache and Nginx, but you could also use tools like HAProxy or Varnish. Nginx is the recommended choice as reverse proxy.


Helfertool uses the domain, which is used to access the page, to generate URLs for e-mails. If your instance is reachable with different domain names, this may be confusing.

It may be desirable that the same URL is used always. This can be achived with a redirect in the reverse proxy. The nginx configuration below contains this redirect.


sudo apt install nginx

Place the configuration in /etc/nginx/sites-available/helfertool.conf, review and adapt the settings carefully.

upstream helfertool {

server {
        # server info
        listen 80 default_server;
        listen [::]:80 default_server;

        server_tokens off;

        # redirect to https
        return 301 https://$server_name$request_uri;

        # logging
        access_log /var/log/nginx/helfertool.log;
        error_log /var/log/nginx/helfertool_error.log error;

server {
        # server info
        listen 443 ssl http2 default_server;
        listen [::]:443 ssl http2 default_server;

        # tls config
        ssl_certificate /etc/letsencrypt/live/;
        ssl_certificate_key /etc/letsencrypt/live/;

        ssl_protocols TLSv1.2 TLSv1.3;
        ssl_prefer_server_ciphers off;

        add_header Strict-Transport-Security "max-age=15552000";

        ssl_stapling on;
        ssl_stapling_verify on;

        # redirect to "" if necessary (without www)
        if ($host != '') {
                return 301$request_uri;

        # proxy
        location / {
                proxy_pass http://helfertool;

                proxy_redirect     off;

                proxy_set_header Host $host;
                proxy_set_header X-Forwarded-For $remote_addr;
                proxy_set_header X-Forwarded-Proto $scheme;

        # proxy error page
        error_page 502 /unavailable.html;

        location = /unavailable.html {
                root /usr/share/helfertool/;

        # post size
        client_max_body_size 50M;

        # logging
        access_log /var/log/nginx/helfertool.log;
        error_log /var/log/nginx/helfertool_error.log error;

Then activate the new vHost and if necessary disable the default vHost.

sudo ln -s /etc/nginx/sites-available/helfertool.conf /etc/nginx/sites-enabled/helfertool.conf
sudo rm /etc/nginx/sites-enabled/default
sudo systemctl restart nginx


sudo apt install apache2

Place the configuration in /etc/apache2/sites-available/helfertool.conf.


This configuration example is missing, sorry!

The Apache module remoteip needs to be enabled. Then activate the new vHost and if necessary disable the default vHost.

sudo a2enmod remoteip

sudo a2ensite helfertool.conf
sudo a2dissite 000-default.conf  # for a new apache installation
sudo a2enmod rewrite ssl headers
sudo systemctl restart apache2

First steps

Try to access the website, it should work now!

To finalize the installation and create an admin account, run:

sudo helfertoolctl init
sudo helfertoolctl createadmin