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 forsudo
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. the following parameters must be adapted:
Placeholder | Description |
---|---|
%EXT_HOSTNAME_URL% | The external address of the Relution server, e.g.https://mdm.example.com |
%MYSQL_PASSWORD% | The password of the Relution database user |
%SYSTEM_ADMIN_PASSWORD% | The initial password of the system administrator. Change this after the first login and then remove this line |
%SYSTEM_ADMIN_EMAIL% | The mail address of the system administrator |
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
Nginx (“engine x”) is used as a reverse proxy to enable access to Relution and simultaneously provide SSL/TLS encryption. Without Nginx or a similar proxy, access to Relution is only possible locally via localhost.
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 →
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:
Parameter | Description |
---|---|
%EXT_HOSTNAME% | Must match the Common Name (cn) of the SSL certificate. |
%SSL_CERT_PATH% | Path to the SSL certificate |
%SSL_CERT_KEY_PATH% | Path to the key of the SSL certificate |
%SSL_CERT_CHAIN_PATH% | Path to the SSL certificate chain |
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.