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
(orsudo
) 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 |
---|---|
%MYSQL_ROOT_PASSWORD% |
Root password for MariaDB |
%MYSQL_PASSWORD% |
Password for the |
%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 ( |
%EXT_HOSTNAME_URL% |
The external URL (e.g. |
%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.