Linux (Alma)

Introduction #

Follow these instructions to set up Relution 5 on AlmaLinux 8 or 9. These instructions use MariaDB as the database and nginx as a reverse proxy.

For additional 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 are also possible.

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

Prerequisites #

Before you begin, make sure that:

• The machines can connect to the internet.
• You are a root user or have the permission for sudo commands.
• You have a valid SSL certificate for your external hostname.

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

Certificates from Let’s Encrypt → are tested and work.

Preparation #

Make sure your system is up to date and wget is installed. These instructions use wget to download scripts from our GitHub repository. If you are familiar with curl, you can alternatively replace wget with curl.

sudo yum -y update
sudo yum -y install wget

During this installation, some files must be edited manually. If you are familiar with vim, you can set it as the default editor with the following 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

Optional: Install password generator #

By default, pwgen (password generator) is not available in Alma Linux. To use it, you must first activate the epel (Extra Packages Enterprise Linux) repository. Since this is an unsupported third-party repository, you will have to install it manually. If you do not want to install these packages on your server you can skip this step and generate secure passwords on another machine.

sudo yum -y install epel-release
sudo yum -y install pwgen

Install MariaDB #

Please use the LTS version of MariaDB. Check which version is the latest stable version MariaDB →

The 10.11 is an LTS version that can also be used.

Also check which version can be installed directly:

sudo dnf module list mariadb

This is an older version. For this reason, it should not be used.

It is possible to install version 11.1 instead. Since version 10.11 is an LTS version, we show here how to install it.
Execute this command:

sudo vi /etc/yum.repos.d/mariadb.repo

Then insert this section and save the file.

[mariadb]
name = MariaDB
baseurl = http://yum.mariadb.org/10.11/rhel8-amd64
module_hotfixes=1
gpgkey=https://yum.mariadb.org/RPM-GPG-KEY-MariaDB
gpgcheck=1

Next, the repository must be updated.

sudo dnf update

Now MariaDB can be installed. Follow the on-screen instructions.

sudo dnf install mariadb-server mariadb

Configuring MariaDB for Relution #

Download the relution.cnf template from the GitHub Repository and save it under /etc/my.cnf.d/relution.cnf.

wget https://raw.githubusercontent.com/relution-io/relution-setup/master/native/Linux/etc/my.cnf.d/relution.cnf.template
sudo mv relution.cnf.template /etc/my.cnf.d/relution.cnf
sudo chmod og-w /etc/my.cnf.d/relution.cnf

If SELinux is operated in Enforcing Mode (default), the permissions for the file after moving it are incorrect.

Run the following command to correct them. Otherwise SELinux will prevent the service from accessing the file for security reasons.

sudo restorecon -v /etc/my.cnf.d/relution.cnf

Start MariaDB and make sure that the service is started automatically after a system restart.

sudo systemctl start mariadb.service
sudo systemctl enable mariadb.service

Check MariaDB installation #

You should now be able to connect to this MariaDB instance. Note that for reasons of downward compatibility, the command line tools still use mysql. This is not a bug.

mysql -u root

You should see an output similar to the following:

Welcome to the MariaDB monitor.  Commands end with ; or \g.
Your MariaDB connection id is 2
Server version: 5.5.56-MariaDB MariaDB Server

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

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

MariaDB [(none)]>

Enter this command to check whether the collation of the server and the database are set as desired to utf8mb4:

SHOW VARIABLES LIKE '%collation%';

Make sure that collation_database and collation_server have been configured to utf8mb4_general_ci.

Press Ctrl+D to disconnect from the database and return to the command prompt.

Create Relution Database #

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

wget https://raw.githubusercontent.com/relution-io/relution-setup/master/native/Linux/scripts/create_database.sh --directory-prefix=/opt

Make sure that the file is executable by root:

chmod 700 /opt/create_database.sh

(Optional) Use pwgen to generate a secure password:

pwgen -snc 48 1

Run the script to create the database:

/opt/create_database.sh "relution" "<password>"

This will create a new database called relution and a new database user named relution who has full rights to this database created.

This user will be used by the Relution service to access to the database. If administrative access to the database for maintenance purposes, we recommend that you create a separate database user for this purpose.

Make sure that you store the password without the inverted commas in a safe place. You will need to use this password later to grant Relution access to the database.

Make sure that you can connect to the database as this user:

mysql -u relution -p relution

Enter the password when prompted. You should use Ctrl+D in the MariaDB prompt as described above to log out again.

Firewall configuration #

If you are installing Relution on another machine, you must set the 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.

Replace ADDRESS with the IP address and netmask of the machine or network you want to grant access to this MariaDB instance. Examples: Use 192.168.0.1/32 to grant the access to the machine with the IP address 192.168.0.1. Use 192.168.0.0/24 to give access from any machine in the IP address range 192.168.0.x. If in doubt, ask your network administrator.

sudo firewall-cmd --permanent --zone=public --add-rich-rule='rule family="ipv4" source address="###ADDRESS###" port protocol="tcp" port="3306" accept'
sudo firewall-cmd --reload

Install Relution #

JAVA #

Install the following packages. Including Java.

sudo yum -y install java-21-openjdk unzip wget

Congigure Java home

sudo echo "export JAVA_HOME=/usr" >> /etc/profile.d/relution_profile.sh
source /etc/profile

Ensure that the changes have been applied

echo $JAVA_HOME

This path should be displayed (/usr).

Create a Relution User #

Create a user without permissions, so that Relution can be executed with this user:

useradd -s /usr/bin/false -r relution

This creates an unprivileged user with the name relution which is used to run the relution service. This is done for security reasons, as running services with `root’ privileges is not recommended.

Download Relution #

Download and unzip the Relution package:

wget http://repo.relution.io/package/latest/relution-package.zip --directory-prefix=/opt
unzip /opt/relution-package.zip -d /opt

Set owner of relution directory:

sudo chown -R relution:relution /opt/relution

Relution Basic Configuration #

Download Relution configuration file:

wget https://raw.githubusercontent.com/relution-io/relution-setup/master/native/Linux/opt/relution/application.yml.template

Edit the application.yml.template and adapt it to your environment. All parameters with placeholders such as %VALUE%, for example.%MYSQL_PASSWORD% must be adapted. At least the following parameters must be adapted:

NOTE: Consider using pwgen to generate the initial password for your administrative account. We recommend changing the password after you have logged in for the first time.

Move the file to the installation directory of the Relution server:

mv application.yml.template /opt/relution/application.yml

Ensure that only root can edit this file and allow relution to read it.

chown root:relution /opt/relution/application.yml
chmod 640 /opt/relution/application.yml

Test installation #

To verify that the setup is correct up to this point, start the Relution service in the foreground.

cd /opt/relution
sudo -u relution JAVA_HOME=/usr bin/relution-foreground.sh

Wait until the Relution service has started. As soon as the terminal output has stopped moving, you should be able to connect to the portal with a browser. To connect from a remote computer, ensure that port 8080 is open in the computer’s firewall. For security reasons, you should close this port as soon as Relution and Nginx are configured. Note that a login via port 8080 is only possible from localhost or 127.0.0.1.

http://<hostname>:8080

How to temporarily allow connections via port 8080 until the next server restart:

sudo firewall-cmd --zone=public --add-port=8080/tcp

If everything works, you should be able to see the Relution portal and log in with the administrative account defined in the application.yml file. For security reasons you should change the administrator’s password after you have logged in. Consider removing the original organisation and the administrator configuration from application.yml.

If you get errors, check that you have followed all the above steps. Use Ctrl+C" to stop the service and wait until the service has shut down. If the service does not stop, use the “Ctrl+C” key combination again.

Creating the systemd service file #

To start Relution as a system service, create a systemd service file for Relution. You can download the file from our GitHub repository.

wget https://raw.githubusercontent.com/relution-io/relution-setup/master/native/Linux/etc/systemd/system/relution.service.template

Move the file to the systemd directory.

sudo mv relution.service.template /etc/systemd/system/relution.service

Reload the systemd daemon to take over the new service.

sudo systemctl daemon-reload

If SELinux is operated in Enforcing Mode (default), the permissions for the file may be the permissions for the file may be incorrect after it has been moved.

Execute the following command to correct them. Otherwise SELinux will prevent the service from accessing the file for security reasons.

sudo restorecon -v /etc/systemd/system/relution.service

Make sure that the Relution directories are still accessible for the service. If the application has previously been started as root Relution may not be able to write to the log files.

sudo chown -R relution:relution /opt/relution
sudo chown -R relution:relution /tmp/relution.tmp

Start Relution and make sure that the service is started automatically after a restart of the system.

sudo systemctl start relution
sudo systemctl enable relution

To monitor the start of the service, you can follow its log file. (press CTRL+C to quit).

tail -f /opt/relution/log/relution.log

Wait until the Relution service has started. You should now be able to open the Relution Portal with a browser again.

http://<hostname>:8080

It is also recommended to close the firewall port that was open for the test. Otherwise, the port will remain open until the next reboot of the system. If Nginx is to be installed on another computer you can skip this step and continue with the firewall configuration below.

sudo firewall-cmd --zone=public --remove-port=8080/tcp

Firewall configuration #

If you install Nginx on another computer, you must leave port 8080 permanently open on that machine, so that Nginx can communicate with Relution.If Nginx is to be installed on the same machine you can skip these steps.

sudo firewall-cmd --permanent --zone=public --add-rich-rule='rule family="ipv4" source address="###ADDRESS###" port protocol="tcp" port="8080" accept'
sudo firewall-cmd --reload

Install Nginx #

Prerequisites #

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

convert SSL certificate →.

Copy these files to the server on which you will be setting up Nginx (e.g. via SSH). Move these files to the appropriate directories and back them up as needed.

Move the certificate file to its default location:

mv server.pem /etc/pki/tls/certs
chown root:root /etc/pki/tls/certs/server.pem
chmod 644 /etc/pki/tls/certs/server.pem

The certificate is public, it is sent to anyone who connects to your website. It is OK to make this file readable by anyone.

Move the certificate key to its default location:

mv server.key /etc/pki/tls/private
chown root:root /etc/pki/tls/private/server.key
chmod 600 /etc/pki/tls/private/server.key

If SELinux is in enforcing mode (default), the security context of the files may be wrong after moving. Run the following commands to correct this. Otherwise SELinux will prevent services from accessing these files for security reasons.

sudo restorecon -v /etc/pki/tls/certs/server.pem
sudo restorecon -v /etc/pki/tls/private/server.key

For security reasons these files are ignored if their permissions are set correctly. Make sure that you have set the permissions as have been set as described above. The private key must only be readable by root. Make sure you keep this file secure. Anyone who has access to this key can sign data on your behalf and decrypt private information sent to you.

If you use Let's Encrypt and Certbot → you should make sure that the keys are stored in a secure place.

Installing Nginx #

Install the necessary packages:

sudo yum -y install epel-release
sudo yum -y install nginx

Create secure Diffie-Hellman parameters #

sudo openssl dhparam -out /etc/nginx/dhparams.pem 4096

This can take a very long time, depending on the server performance. Create a cache directory for nginx. This is used to cache downloaded large files.

sudo mkdir /usr/share/nginx/cache
sudo chown nginx:nginx /usr/share/nginx/cache

Download the configuration files:

wget https://raw.githubusercontent.com/relution-io/relution-setup/master/native/Linux/etc/nginx/conf.d/relution-ssl.conf.template
wget https://raw.githubusercontent.com/relution-io/relution-setup/master/native/Linux/etc/nginx/conf.d/relution-location.include.template

Edit the relution-ssl.conf.template and adapt it to your environment. All parameters with placeholders %VALUE% must be configured. for example: %EXT_HOSTNAME%. These parameters are:

If your Relution server is on another computer, change the IP address in the proxy_pass parameters to the IP address of the relution server. Note that this option is present both in relution-ssl.conf.template and in relution-location.include.template.

• From proxy_pass http://127.0.0.1:8080;
• To proxy_pass http://<relution-ip>:8080;

If you do not want to use OCSP, comment out the following options:

#    ssl_stapling on;
#    ssl_stapling_verify on;
#    ssl_trusted_certificate %SSL_CERT_CHAIN_PATH%;

If you plan to install native Windows apps with Relution on Windows devices, comment out the following lines:

Otherwise the installation of the apps will fail.

Move the files to the target directories:

sudo mv relution-ssl.conf.template /etc/nginx/conf.d/relution-ssl.conf
sudo mv relution-location.include.template /etc/nginx/conf.d/relution-location.include

If SELinux is operated in Enforcing Mode (default), the permissions for the file are incorrect after moving. Run the following command to correct them. Otherwise SELinux will prevent the service from accessing the file for security reasons.

sudo restorecon -v /etc/nginx/conf.d/relution-ssl.conf
sudo restorecon -v /etc/nginx/conf.d/relution-location.include

Check the configuration with this command:

sudo nginx -t

You should get a message like syntax is okay and test is successful. If you get errors, check your Nginx configuration for typos.

Default server #

The default configuration of Nginx configures a site for its placeholder web site. If Relution’s web application is the only site hosted on this server, you can disable this “default server” and make Relution the default. If you are hosting multiple sites (“virtual hosts”), skip this step.

Open the global Nginx configuration:

sudo vi /etc/nginx/nginx.conf

Comment on the server { ... } area:

#    server {
#        listen       80 default_server;
#        listen       [::]:80 default_server;
        [...]
#    }

There is another server { ... } area for SSL (i.e. HTTPS). Comment this out as well:

#    server {
#        listen       443 ssl default_server;
#        listen       [::]:443 ssl;
        [...]
#    }

Change the Nginx configuration for Relution:

sudo vi /etc/nginx/conf.d/relution-ssl.conf

Add default_server to the first list option of each server. It should look similar to this:

    server {
        listen 0.0.0.0:80 default_server;
        listen [::]:80;
    [...]

    server {
        listen 0.0.0.0:443 ssl default_server;
        listen [::]:443 ssl;
    [...]

If you plan to install native Windows apps with Relution on Windows devices, comment out the following lines:

Otherwise, the installation of the apps will fail.

Check that your Nginx configuration is valid:

sudo nginx -t

If you get a message like syntax is okay and test is successful, this is the case…. If you get error messages, please check the configuration.

Start and activate Nginx service #

If everything is OK, start and activate the Nginx service:

sudo systemctl start nginx
sudo systemctl enable nginx

If you get error messages or the service does not start, look at this log: (/var/log/nginx/error.log).

Firewall #

Open ports 80 and 443 in the firewall so that HTTP and HTTPS work.

sudo firewall-cmd --permanent --zone=public --add-port=80/tcp
sudo firewall-cmd --permanent --zone=public --add-port=443/tcp
sudo firewall-cmd --reload

SELinux Configuration #

You may not be able to connect to https://<your-fqdn-hostname> immediately. If this is the case, check the error logs of Nginx.

cat /var/log/nginx/relution_error.log | grep "13: Permission denied"

You may see error messages like this:

2022/06/27 18:12:41 [crit] 11111#0: *2 connect() to <relution-ip>:8080 failed (13: Permission denied) while connecting to upstream, client: <client-ip>, server: <your-fqdn-hostname>, request: "GET / HTTP/1.1", upstream: "http://<relution-ip>:8080/", host: "<nginx-ip>"

Check if it is indeed an SELinux problem:

sudo cat /var/log/audit/audit.log | grep nginx | grep denied

You should see one or more denied messages similar to this:

type=AVC msg=audit(1524845545.644:365): avc: denied { name_connect } for pid=11111 comm="nginx" dest=8080 scontext=system_u:system_r:httpd_t:s0 tcontext=system_u:object_r:http_cache_port_t:s0 tclass=tcp_socket

Allow nginx to connect to the other machine:

sudo setsebool -P httpd_can_network_connect 1

You should now be able to connect to your Relution instance via HTTPS.