How to Install on Windows

Instructions were last verified on Windows Server 2016, 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 machines can connect to the Internet
You have administrator 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.

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.

Docker for Windows requires Windows 10 Pro/Enterprise or Windows Server 2016 RTM and the Hyper-V and Containers features must be enabled. For older versions of Windows, please use Docker Toolbox which uses VirtualBox for virtualization.

The Docker service should be started automatically once installation completes. You should be able to see Docker’s whale icon in the notification area. You should see Docker.Service as a background process in task manager.

Docker for Windows is not supported for nested virtualization scenarios. It might work in some cases, and not in others. This means Docker should really be installed on a Windows Server that runs on physical hardware. If you want to use a virtual machine we highly recommend the use of Linux to run Docker. Docker on Linux does not use virtualization for its containers which also makes it less resource intensive.

Install docker compose

Please follow the official installation instructions on Install Docker Compose to install docker-compose on your server. On Windows, docker-compose should already be installed as part of the Docker installation.

Once you have installed Docker and docker-compose, continue with the steps below.

Download the docker-compose file

Download the docker-compose.yml from our GitHub repository.

Move the file to "%ProgramFiles%\relution\".

Configure the containers

Adjust the file to your environment. You can edit the file with a text editor like Notepad or Notepad++.

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
%MONGODB_ROOT_PASSWORD%	Root password for MongoDB
%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

%MONGODB_ROOT_PASSWORD%

Root password for MongoDB

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

Configure the environment of the relution container as needed.

Configure the NGINX_HOST for the nginx container to use your actual domain name.

When you shut down a Docker container, all data inside the container is potentially lost. This means any data that needs to be persisted must be stored outside the container. Since Relution stores all of its data in the databases only the databases need to be backed up. The containers themselves are “disposable”. Make sure to include MariaDB and MongoDB in your backup strategy. The configuration above maps the data directories of MariaDB and MongoDB to Docker volumes named mariadb and mongodb respectively.

Configure nginx

Download the nginx configuration file relution-nginx.conf from our GitHub repository. If required, edit and adjust the file for your environment.

Move the file into the same directory as the docker-compose.yml, e.g. "%ProgramFiles%\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:
     - 'C:\Program Files\relution\relution-nginx.conf:/etc/nginx/conf.d/relution-nginx.conf'
     - 'C:\Program Files\relution\server.pem:/etc/nginx/server.pem'
     - 'C:\Program Files\relution\server.key:/etc/nginx/server.key'

The configuration above expects your SSL certificate and key to reside in "%ProgramFiles%\relution\server.pem" and "%ProgramFiles%\relution\server.key". If these files are in a different location adjust the volumes of the nginx container accordingly.

Configure MariaDB

Download the MariaDB configuration file relution.cnf from our GitHub repository.

Move the file into the same directory as the docker-compose.yml, e.g. "%ProgramFiles%\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'
      - 'C:\Program Files\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. Open the Windows Command shell for this.

cd "%ProgramFiles%\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 output 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 "%ProgramFiles%\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 "%ProgramFiles%\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.