How to Install on Linux

Instructions were last verified on CentOS 7.4, current as of May 2018. We recommend the use of Linux for the host system.

Follow these instructions to run Relution in a Docker container. You can use this to run Relution on any operating system supported by Docker, you are not restricted to operating systems supported by Relution.

These instructions cover installation and configuration of a basic Relution instance in a Docker container with required services also running in Docker containers.

Prerequisites

Before you start, ensure that:

The host machine can connect to the Internet
You have root (or sudo) permission
You have a valid SSL certificate for your external host name

Self signed certificates will not work, because mobile devices do not trust them. You can manually install your root certificate on a device to get it to trust your certificate, but this takes a lot of work and is not recommended. Certificates from Let’s Encrypt have been known to work. Be aware that older devices may not trust these certificates, as they were established as a Certificate Authority (CA) fairly recently.

Preparation

During this installation some files will need to be edited manually. If you are familiar with vim set it as default editor with the commands below. If you are not familiar with vim please skip this and keep using the default editor.

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

Overview

The Relution installation consists of setting up the following components:

Install Docker and docker-compose
Configure the Relution container
Configure nginx

Install Docker and docker-compose

To run Relution in a Docker container, you’ll first need to install Docker and docker-compose.

Install Docker

Please follow the official installation instructions on Docker Community Edition to install Docker on your server. On most Linux distributions Docker should be part of the repository.

Make sure to start and enable the Docker service after installation, so it is available after a system reboot.

sudo systemctl start docker
sudo systemctl enable docker

Install docker compose

Please follow the official installation instructions on Install Docker Compose to install docker-compose on your server. Once you have installed Docker and docker-compose, continue with the steps below.

Configure the containers

Create a directory for the docker-compose configuration file.

mkdir -p /opt/relution

Download and edit the configuration file.

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

editor /opt/relution/docker-compose.yml

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

Placeholder Description

Placeholder	Description
%MYSQL_ROOT_PASSWORD%	Root password for MariaDB
%MYSQL_PASSWORD%	Password for the `relution` database user — Set the same password on both MariaDB & Relution
%MONGODB_ROOT_PASSWORD%	Root password for MongoDB — Set the same password on both MongoDB & Relution
%SMTP_HOSTNAME%	The hostname of your SMTP server
%SMTP_PORT%	The port of your SMTP server (default: 25)
%SMTP_USERNAME%	The username of a user on the SMTP server
%SMTP_PASSWORD%	The password of a user on the SMTP server
%EXT_HOSTNAME%	The external hostname for your Relution server. This must match the Common Name (`cn`) of your SSL certificate
%EXT_HOSTNAME_URL%	The external URL (e.g. `https://<ext_hostname>`)
%SYSTEM_ADMIN_PASSWORD%	The initial password of the system administrator. Change this after first sign in
%SYSTEM_ADMIN_EMAIL%	The system administrator’s email address
%ORG_UNIQUE_NAME%	The unique name of the initial Relution organization to create
%ORG_DISPLAY_NAME%	The name of the initial Relution organization to create
%ADM_USERNAME%	The username of the organization administrator
%ADM_PASSWORD%	The password of the organization administrator
%ADM_FIRST_NAME%	The name of the organization administrator
%ADM_LAST_NAME%	The family name of the organization administrator
%ADM_EMAIL%	The email address of the organization administrator

%MYSQL_ROOT_PASSWORD%

Root password for MariaDB

%MYSQL_PASSWORD%

Password for the relution database user — Set the same password on both MariaDB & Relution

%MONGODB_ROOT_PASSWORD%

Root password for MongoDB — Set the same password on both MongoDB & Relution

%SMTP_HOSTNAME%

The hostname of your SMTP server

%SMTP_PORT%

The port of your SMTP server (default: 25)

%SMTP_USERNAME%

The username of a user on the SMTP server

%SMTP_PASSWORD%

The password of a user on the SMTP server

%EXT_HOSTNAME%

The external hostname for your Relution server. This must match the Common Name (cn) of your SSL certificate

%EXT_HOSTNAME_URL%

The external URL (e.g. https://<ext_hostname>)

%SYSTEM_ADMIN_PASSWORD%

The initial password of the system administrator. Change this after first sign in

%SYSTEM_ADMIN_EMAIL%

The system administrator’s email address

%ORG_UNIQUE_NAME%

The unique name of the initial Relution organization to create

%ORG_DISPLAY_NAME%

The name of the initial Relution organization to create

%ADM_USERNAME%

The username of the organization administrator

%ADM_PASSWORD%

The password of the organization administrator

%ADM_FIRST_NAME%

The name of the organization administrator

%ADM_LAST_NAME%

The family name of the organization administrator

%ADM_EMAIL%

The email address of the organization administrator

This docker-compose file defines four services: mariadb, mongodb, relution and nginx.

Make sure to replace the passwords defined in this file with more secure versions, e.g. use pwgen -snc 48 1 to generate secure random passwords. With the exception of the organization administrator’s password these passwords do not need to be entered by a human so there is no reason to use weak passwords.

When you replace the password placeholder on a database container (e.g. %MYSQL_PASSWORD%) make sure to configure the same password for the Relution container. Otherwise the Relution container won’t be able to connect to the database.

When you shut down a Docker container, data inside the container is potentially lost. This means data that needs to be persisted must be stored outside the container (e.g. on a mounted volume). The default configuration maps the data directories of MariaDB and MongoDB to Docker volumes named mariadb and mongodb respectively. Relution stores all of its data in the database, so no additional configuration should be needed. Make sure to include MariaDB and MongoDB in your backup strategy.

Configure nginx

Download the nginx configuration file. If required, edit and adjust the file for your environment.

wget https://raw.githubusercontent.com/relution-io/relution-setup/master/docker/Linux/opt/relution/relution-nginx.conf --directory-prefix=/opt/relution

For increased security consider enabling SSL stapling and using better DH parameters. Provide the files as needed and then uncomment the ssl_dhparam and ssl_stapling options.

The relution-nginx.conf file is mounted into the docker container as a volume in the docker-compose.yml file like this:

    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'

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

Configure 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 to support Emojis and other Unicode characters. Without this configuration import of apps that use these characters in their app name or description will fail.

The relution.cnf file is mounted into the docker container as a volume in the docker-compose.yml file like this:

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

If you want to move this file to a different location, make sure to update the volumes of the mariadb container accordingly.

Start Relution

To start Relution you can now use docker-compose to start all the Docker containers defined in the yaml file.

cd /opt/relution/
docker-compose up --detach

This will download the Docker image of each service defined in the docker-compose.yml file before starting a Docker container for each service. Images are cached on the local machine, so future starts will be faster.

It will take some time for the services to start up once the downloads complete. To see the log ouput of a specific container use the following command:

docker logs --follow <container_name>

For example use docker logs -f docker_relution to follow the log output of Relution’s container.

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

Updating Relution running inside a docker container is as simple as:

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

Replace <container_name> with the name of the Relution container you’ve specified in your docker-compose.yml. The default name used in our templates is docker_relution.

This will download the latest Docker image of each container before restarting the containers. The Relution service will be unavailable until containers have finished rebooting.