Docker (recommended)

Introduction #

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.

Prerequisites #

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).

Preparation #

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 yum -y install vim
sudo update-alternatives --install /usr/bin/editor editor /usr/bin/vim 100

Overview #

Components:

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 and docker-compose.

Install Docker #

Please follow these commands for Alma Linux:

dnf install -y dnf-utils wget
yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
dnf install -y docker-ce docker-ce-cli containerd.io

Install Docker Compose

curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
chmod +x /usr/local/bin/docker-compose

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

Create a directory for Relution:

mkdir /opt/relution/

Configure container #

Create a directory for the configuration file of docker-compose.

mkdir -p /opt/relution

Load and edit configuration files #

docker-compose.yml #

wget https://raw.githubusercontent.com/relution-io/relution-setup/master/docker/Linux/opt/relution/docker-compose.yml \
    --directory-prefix=/opt/relution

vi /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:

application.yml #

wget https://raw.githubusercontent.com/relution-io/relution-setup/master/docker/Linux/opt/relution/application.yml \
    --directory-prefix=/opt/relution

editor /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:

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 https://raw.githubusercontent.com/relution-io/relution-setup/master/docker/Linux/opt/relution/relution-nginx.conf \
    --directory-prefix=/opt/relution

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

relution-nginx.conf

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:

        volumes:
         - '/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 https://raw.githubusercontent.com/relution-io/relution-setup/master/docker/Linux/opt/relution/relution.cnf \
    --directory-prefix=/opt/relution

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:

        volumes:
          - '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.