Docker (recommended)


This manual was last checked on Alma Linux 8 and 9, as of August 2023. We recommend using Linux for the host system.

This guide covers the installation and configuration of a basic Relution instance running in Docker containers.


Before you start, make sure that:

  • The host computer can connect to the internet.
  • You are a root user or have the permission for sudo commands.
  • You have a valid SSL certificate for the URL.

Self-signed certificates do not work, as mobile devices do not do not trust them. You can install your root certificate manually on a device so that the device trusts your certificate.

As this involves a lot of work, this approach is not recommended. Certificates from Let’s Encrypt → have been tested and work. Note that older devices may not trust these certificates, as they have only been recently set up as a certification authority (CA).


During this installation, some files must be edited manually. If you are familiar with vim, set it as the default editor with the commands. If you are not familiar with vim, please skip this section and continue to use the default editor.

sudo dnf install -y vim
sudo update-alternatives --install /usr/bin/editor editor /usr/bin/vim 100



  1. install Docker and Docker Compose
  2. configure the containers
  3. Configure nginx

Install Docker and Docker Compose

To run Relution in a Docker container, you must first install Docker including docker compose.

Install Docker

Please follow these commands for Alma Linux:

dnf install -y dnf-utils wget
yum-config-manager --add-repo
dnf install -y docker-ce docker-ce-cli docker-compose-plugin

After installation, make sure that you start and activate the Docker service, so that it is available after a system reboot.

systemctl enable docker
systemctl start docker

Configure container

Create a directory for the Relution configuration files, e.g. for `docker compose.

mkdir -p /opt/relution

Load and edit configuration files


wget \
vim /opt/relution/docker-compose.yml

Adapt the file to your environment. All values that need to be replaced have placeholders in the form of ${Value}, for example ${MYSQL_ROOT_PASSWORD}. You must replace at least the following values:

${MYSQL_ROOT_PASSWORD}Root password of the MariaDB
${MYSQL_PASSWORD}The password of the Relution database user
${EXTERNAL_HOSTNAME}The external hostname under which Relution will be accessible


wget \
vim /opt/relution/application.yml

Adapt the file to your environment. All values that need to be replaced have placeholders in the form of %VALUE%, for example %EXT_HOSTNAME%. You must replace at least the following values:

%EXT_HOSTNAME_URL%The external address of the Relution server, e.g.
%MYSQL_PASSWORD%The password of the Relution database user
%SMTP_HOSTNAME%The host name of the SMTP server
%SMTP_PORT%The port of the SMTP server (default: 25)
%SMTP_USERNAME%The user name of the SMTP server
%SMTP_PASSWORD%The password of the SMTP Server user
%SYSTEM_ADMIN_PASSWORD%The initial password of the system administrator Change this after the first login and then remove this line
%SYSTEM_ADMIN_EMAIL%The mail address of the System Administrator

The Docker Compose file defines three services: mariadb, relution and nginx.

Make sure that you replace the passwords defined in this file with more secure passwords. For example, you can use pwgen -snc 48 1 to generate to create secure random passwords.

If you replace the password placeholder on a database container e.g. %MYSQL_PASSWORD%, make sure you use the same password in application.yml.

If you shut down a Docker container, data inside the container is potentially lost. This means that persisted data should be stored outside the container (e.g. on a mounted volume).

The default configuration maps MariaDB’s data directories to the host system. Relution stores all its data in the database, so no additional configuration is required.

Configuration of nginx

Download the nginx configuration file. Edit it and adapt the file to your environment if necessary.

wget \

For increased security, you should enable SSL stacking and use better DH parameter. Provide the files as needed and then enable the ssl_dhparam and ssl_stapling options in relution-nginx.conf.

Generate key

openssl dhparam -out /opt/relution/dhparams.pem 4096


ssl_dhparam /etc/nginx/dhparams.pem;

The file relution-nginx.conf is included in the Docker container as a volumevia the filedocker-compose.yml` as follows:

  - "/opt/relution/relution-nginx.conf:/etc/nginx/conf.d/relution-nginx.conf"
  - "/opt/relution/server.pem:/etc/nginx/server.pem"
  - "/opt/relution/server.key:/etc/nginx/server.key"
  - "/opt/relution/dhparams.pem:/etc/nginx/dhparams.pem"

The configuration expects that your SSL certificate and your key in /opt/relution/server.pem and /opt/relution/server.key. respectively. If these files are in a different location or have a different name, adjust the volumes of the nginx container accordingly.

Convert SSL certificate →

Configuring MariaDB

Download the MariaDB configuration file.

wget \

This file configures MariaDB to use utf8mb4, which is required for support for emojis and other Unicode characters. Without this configuration, the import of apps that use these characters in their app name or description will fail.

NOTE: The relution.cnf file is placed in the Docker container as a volume in the docker-compose.yml file as follows:

  - "mariadb:/var/lib/mysql"
  - "/opt/relution/relution.cnf:/etc/mysql/conf.d/relution.cnf"

If you wish to move this file to another location, you must update the volumes of the mariadb container accordingly.

Start Relution

To start the Docker containers defined in the yaml file, use the following commands

cd /opt/relution/
docker compose up -d

This will download the Docker image of each service defined in the docker-compose.yml file. The images are cached on the local machine so that future launches are faster.

It takes some time for the services to be started once the downloads are completed. To see the log output of a particular container, use the following command:

docker logs -f <container_name>

For example, use docker logs -f docker_relution to view the log output of Relution.

To shut down and remove the containers, use the following command:

cd /opt/relution/
docker compose down

This will not remove the downloaded images.

Update Relution

cd /opt/relution/
docker compose pull
docker compose up -d

This will download the latest Docker image for each container before the containers are restarted. The Relution service will not be available until the restart of the containers is complete.

Checklist on-premise installation

This checklist is used to record the current status of the installation in the event of problems and to enable more precise support.

1. basic installation HostCompleted
1.1 Linux distribution installed (Alma / Rocky)Yes / No
1.2 Internet available on host (ping)Yes / No
1.3 Root / Sudo available on the hostYes / No
1.4 Valid SSL certificate available for the URLYes / No
1.5 SSH or Teamviewer ConnectionYes / No
2. Necessary softwareCompleted
2.1 Text editor installed (Vim / Nano)Yes / No
2.2 Docker installedYes / No
2.3 docker compose installedYes / No
2.4 Docker service activated and startedYes / No
3. Preparation of configuration filesCompleted
3.1 Relution directory createdYes / No
3.2 docker-compose.yml loadedYes / No
3.3 Placeholder in the docker-compose.yml editedYes / No
3.4 Reverse proxy necessary?Yes / No
3.5 application.yml loadedYes / No
3.6 Placeholder in aplication.yml editedYes / No
4. nginx configurationCompleted
4.1 Configuration file loadedYes / No
4.2 DH parameters createdYes / No
4.3 DH parameters specifiedYes / No
4.4 SSL certificate split into pem and keyYes / No
4.5 pem and key specified as volumeYes / No
5. MariaDB configurationCompleted
5.1 Configuration file loadedYes / No
6. RelutionCompleted
6.1 Relution startsYes / No

In case of startup problems with Relution, please send the complete log as a zip file to support.