Windows Server 2019

Introduction #

Follow these instructions to set up Relution 5 on Windows Server 2019. These instructions use MariaDB as the datastore and nginx as the reverse proxy.

For added security and performance, we recommend installing Relution, MariaDB, and nginx on separate machines. Installation on a single machine or on one or more virtual machines is also possible.

This guide covers the installation and configuration of a simple Relution instance.

Prerequisites #

Before you start, make sure that:

• The machines can connect to the Internet
• You have administrative rights
• You have a valid SSL certificate for your external hostname

Self-signed certificates do not work, as mobile devices do not trust them. You can manually install your root certificate on a device to make it trust your certificate. This approach is not recommended.

Certificates from Let’sEncrypt → are tested and work. Note that older devices may not trust these certificates because Let’s Encrypt was only recently established as a certificate authority (CA).

MariaDB installation #

Go to MariaDB → and download the latest stable 64-bit version for Windows. At the time of writing this guide this is mariadb-10.11.5-winx64.msi.

Follow the on-screen instructions for installation.

MariaDB configuration #

Update the configuration of MariaDB with the options required by Relution:

• Go to "%ProgramFiles%\MariaDB 10.11\data".
• Open “my.ini” in a text editor as administrator (e.g. Notepad)
• Find the section “[mysqld]”.

Add these settings to the section “[mysqld]”:

collation-server=utf8mb4_general_ci
character-set-server=utf8mb4
max_allowed_packet=1G
innodb_file_per_table=1

## No longer needed/supported for MariaDB >= 10.2.2
## If you have an older version please update or enable this
#innodb_large_prefix=on
#innodb_file_format=Barracuda

The “[mysqld]” section may already contain a “charset server” setting. Remove this setting and replace it with the one above.

If you are upgrading from an older version of MariaDB, you may still have the innodb_large_prefix and innodb_file_format settings in your my.ini file. These settings are no longer needed and their presence may prevent the MariaDB service from starting correctly.

Restart the MariaDB service by either using the Services Manager (services.msc) or by using the command prompt. Note that for backward compatibility, the service has the name “MySQL” for backward compatibility.

net stop MySQL
net start MySQL

Verify installation #

You should now be able to connect to this MariaDB instance. You can use the the shortcut “MySQL Client (MariaDB 10.11 (x64))”, which the installation program should have created in your start menu. After you have made a connection, you should see an output similar to this:

Enter password: ********
Welcome to the MariaDB monitor.  Commands end with ; or \g.
Your MariaDB connection id is 11
Server version: 10.11.5-MariaDB mariadb.org binary distribution

Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others.

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

MariaDB [(none)]> exit
Bye

Alternatively, you can use the HeidiSQL client which is an optional part of the installer, or the MySQL Workbench to connect to the instance.

Create database #

Next, create the relution database and an associated database user. This user will be used by the Relution service to connect to the database.

Connect to the database using an SQL client. Using a GUI application like HeidiSQL or MySQL Workbench is recommended for this task. Execute the following SQL statements:

CREATE DATABASE relution CHARACTER SET 'utf8mb4' COLLATE 'utf8mb4_general_ci';
CREATE USER 'relution'@'localhost' IDENTIFIED BY '$PASSWORD';
GRANT ALL PRIVILEGES ON relution.* TO 'relution'@'localhost' IDENTIFIED BY '$PASSWORD';
CREATE USER 'relution'@'%' IDENTIFIED BY '$PASSWORD';
GRANT ALL PRIVILEGES ON relution.* TO 'relution'@'%' IDENTIFIED BY '$PASSWORD';
FLUSH PRIVILEGES;

Replace $PASSWORD with a secure random password. We recommend the use of a password manager to create a long random password (e.g. 32 characters or more). This password will be used by the Relution service and does not need to be entered manually by an administrator. Therefore you can use a strong password.

This will create a new database named relution and a new database user named relution, who has full rights for this database, will be created. This user will be used by the relution service to access the database. If administrative access to the database is needed for maintenance purposes it is recommended to create a separate database user for this purpose.

Be sure to save the password. It will be needed later for configuring Relution’s database connection.

Make sure you can connect to the database with this user. Open the Command Prompt (MariaDB 10.6 (x64)) shortcut from the Start menu and enter the following command:

mysql -u relution -p relution

Enter the password when prompted. You should see the MariaDB prompt like the one above. Type exit and press enter to end the session.

Firewall Configuration #

If you are installing Relution on another machine, you will need to open port 3306 on that machine so that Relution can communicate with MariaDB. If Relution is installed on the same machine, you can skip these steps.

• Open Windows Defender Firewall with advanced security.
• Select ‘Incoming rules
• Click on New Rule... on the right side of the page
• Select Program
• Click on Next
• Select This program path.
• Use Browse... to select the MariaDB service exe file (C:\Program Files\MariaDB 10.6\bin\mysqld.exe) * Click Next * Select Allow connection * Click Next * Enable Domain and/or Private - depending on your infrastructure * Click on Next * give the rule a name * Click on Exit.

Relution Installation #

Install Java Runtime #

Download and install a supported Java version. If the installation program asks whether JAVA_HOME should be configured, select Yes.

We currently recommend using OpenJDK 17 (JRE). Most vendors treat this version as a Long Term Support (LTS) release. Be sure to read our change log → for up-to-date information

There are several vendors of OpenJDK, including Eclipse Temurin, Oracle, RedHat and others. For Windows, we recommend Eclipse Temurin →.

Configure #### environment

The following steps are only necessary if the installer does not have the JAVA_HOME` set. The AdoptOpenJDK installer can do this for you. If you have this option enabled, you can skip these steps.

• Click Start and search for `Environment Variables
• Open Edit system environment variables.
• Click on the Advanced tab
• Select Environment variables.
• Click on New... in the System variables.
• Enter JAVA_HOME as the name of the variable
• Enter the installation directory of the JRE/JDK as value for the variable
• Click on OK

Check if JAVA_HOME is set #

If you had a prompt window open before, you must close it before the changes take effect. Open a new Windows command prompt and type the following command.

echo %JAVA_HOME%

You should see the value you entered in the environment variables above. Otherwise please check your settings.

Install Relution #

Download the current Relution package → and extract it.

Note that Windows by default creates a new directory for the extracted files, so relution is located inside the relution-package directory.

Basic configuration of Relution #

Open a text editor (e.g. Notepad) as administrator and paste the following content there:

relution:
  system:
    admin:
      password: %SYSTEM_ADMIN_PASSWORD%
      email: %SYSTEM_ADMIN_EMAIL%
  server:
    externalURL: %EXT_HOSTNAME_URL%
  database:
    type: mysql
    url: jdbc:mariadb://<db-hostname>/relution?useServerPrepStmts=true
    username: relution
    password: %MYSQL_PASSWORD%
  mongodb:
    enabled: false

 #optional parameters:
  mail:
    username: %SMTP_USERNAME%
    password: %SMTP_PASSWORD%
    host: %SMTP_HOSTNAME%
    port: %SMTP_PORT%
  smtp:
    ttls: false
    ssl: false
    ehlo: true
  wizard:
    orga:
      name: %ORG_UNIQUE_NAME%
      fullName: %ORG_DISPLAY_NAME%
      admin:
        username: %ADM_USERNAME%
        password: %ADM_PASSWORD%
        givenname: %ADM_FIRST_NAME%
        surname: %ADM_LAST_NAME%

Make sure you edit the file to fit your environment. The following parameters need to be replaced:

NOTE: Don’t forget to specify the SQL Server in the connection string.

Optional parameters #

Consider using a password generator to create the first password for your administrative account. We recommend changing the password after you log in for the first time.

Save the file as application.yml in the Relution installation directory (e.g. "%ProgramFiles%\relution\application.yml").

Check installation #

To verify that the setup is correct up to this point, start Relution in the foreground. Open a console window as administrator and execute the following commands:

cd "%ProgramFiles%\relution"
windows-bin\relution-foreground.bat

Wait until the Relution is started. As soon as the terminal output has stopped updating, you should be able to connect to Relution with a browser:

http://localhost:8080

If everything works, you should see the Relution portal and be able to log in with the administrative account, which is defined in the file application.yml file. For security reasons, you should change the password of the administrator after logging in. For security reasons, consider removing the organization and administrator configuration from the application.yml.

If you get errors, verify that you have performed all of the above steps. Use Ctrl+C" to stop Relution and wait until Relution shuts down. If Relution does not shut down, use “Ctrl+C” again to force the service to stop.

Set up Relution as a service #

Install Relution as a Windows service, using the batch script install_service.bat. Open a console window as administrator and execute the following commands:

cd "%ProgramFiles%\relution".
windows-bin\install_service.bat

The service should start automatically after installation. Otherwise you can use the service manager or net start relution. Type in the command prompt to start the service.

Configure firewall #

If you install nginx on another machine, you need to open port 8080 to allow nginx to communicate with Relution. If Relution is installed on the same machine, you can skip these steps.

• Open Windows Defender Firewall with advanced security.

• Click on ‘Incoming rules

• Select New Rule... in the action menu

• Select Program

• Click on Next

• Select This program path.

• Browse…` and select the service file of Relution

  (C:\Program Files\relution\windows-bin\nssm.exe) * Click on Next. * Select Allow connection * Click Next * Select Domain and/or Private , depending on your infrastructure * Click on Next * give the rule a name * Click Finish.

Nginx Installation #

Preparation #

You have received a valid SSL certificate and certificate key from your SSL provider (Certificate Authority, CA). If you want to use OCSP stapling, you should also have a certificate chain file.
OCSP stapling →

SSL certificate convert →.

Copy these files to the server where you will be setting up nginx. Move these files to appropriate directories and back them up as needed.

The private key must be readable only by the administrator. Be sure to keep this file secure. Anyone with access to this key can sign data on your behalf and decrypt private information sent to you.

If you are using Let’s Encrypt, please refer to ACME Client Implementations for possible clients available for Windows. The official Certbot is only available for UNIX-like operating systems.
ACME Client Implementations →
Certbot →

Install nginx #

Download the latest stable version of nginx for Windows → to your download directory.

Right-click on the nginx-x.xx.zip file and click Extract All....

Move the extracted directory nginx-x.xx to %ProgramFiles% and rename it to rename it to nginx.

move "%HOMEPATH%\Downloads\nginx-1.14.0\nginx-1.14.0" "%ProgramFiles%\nginx"

Customize the source directory as needed.

By default Windows creates a new directory for the extracted files so that the actual nginx-x.xx directory can be located within another nginx-x.xx directory. Be sure to move the directory that contains the nginx.exe file.

Configure nginx for Relution #

Copy your SSL certificate and private key to %ProgramFiles%\nginx\server.pem and %ProgramFiles%\nginx\server.key.

Copy %ProgramFiles%\relution\proxy\nginx_windows_sample.conf to %ProgramFiles%\nginx\conf\nginx.conf (overwrites the existing file if necessary).

copy `%ProgramFiles%\relution\proxy\nginx_windows_sample.conf` `%ProgramFiles%\nginx\conf\nginx.conf`.

Open the file in a text editor that can work with Linux line endings (for example, Notepad++) and modify the file to suit your environment as needed. If you have installed Relution on a different server, make sure you specify the IP address in proxy_pass http://127.0.0.1:8080; accordingly.

Verify your nginx configuration with the following command:

"%ProgramFiles%\nginx\nginx.exe" -t

You should get syntax is okay and test is successful messages. If you get errors, check your nginx configuration for typos, etc., as shown in the as indicated in the error message.

Install nginx as a Windows service #

Copy nssm.exe and install_service.bat from the proxy directory of Relution to the nginx installation directory

cd "%ProgramFiles%\nginx"
copy "%ProgramFiles%\relution\proxy\nssm.exe" .
Copy "%ProgramFiles%\relution\proxy\install_service.bat" .

Run the batch script install_service.bat as administrator to install install nginx as a Windows service.

"%ProgramFiles%\relution\proxy\install_service.bat"

Firewall #

Open ports 80 and 443 in the firewall to allow access via HTTP and HTTPS.

• Open ‘Windows Firewall with advanced security
• Navigate to ‘Incoming rules
• In the Actions section click on New rule....
• Select Program.
• Click on Next
• Select This program path.
• Use Browse... to select the executable file of the Relution service
  • C:\Programs\nginx\nginx.exe. Click Next
  • Select Allow connection. Click Next
  • Select Public. Click Next
  • Enter a name for the rule and click Complete.