Ermis‐Server Installation Guide 2

Comprehensive guide for installation of ermis-server.

This guide covers versions:

• v1.4.0-rc7
• v1.4.0-rc6
• v1.4.0-rc5
• v1.4.0-rc4
• v1.4.0-rc3
• v1.4.0-rc2
• v1.4.0-rc1

Docker Install

Prerequisites

• Ensure you have Docker and Docker Compose installed on your server.
• SMTP credentials (Gmail, ProtonMail, private Stalwart SMTP server, etc.)

Deployment

1. Create dedicated directory:

   mkdir -p ~/docker/ermis-server
   cd ~/docker/ermis-server

2. Download and extract ermis-docker.tar.gz. You can easily obtain the latest version from GitHub Releases:

   wget https://github.com/Koukobin/Ermis/releases/download/server-vX.Y.Z/ermis-docker-X.Y.Z.tar.gz
   tar -xf ermis-docker-X.Y.Z.tar.gz

3. Setup

   chmod +x setup_configs.sh
   sed -i 's/\[ -s/\[ -n/g' setup_configs.sh
   ./setup_configs.sh

4. Define Secrets

   chmod +x set_secret.sh
   ./set_secret.sh

5. Generate SSL Certificate

   chmod +x gen_certs.sh
   ./gen_certs.sh
   sudo chown 999:999 certs/server_plain.key
   sudo chmod 600 certs/server_plain.key

6. Run Docker

   docker compose up

   If compose runs successfully with no errors, you can run Docker in detached mode using the -d flag:

   docker compose up -d

Tip

You can read docker logs via docker compose logs -f ermis-server

Note

Once a db user is configured - with a db password defined in docker secrets -, his credentials are immutable, meaning that if the db password is subsequently changed using ./set_secret.sh, that change won't be reflected in the actual db user.

Consequently, you have to manually update the db users' password:

docker exec -it ermis-server bash
psql -U postgres
ALTER USER ermis_admin WITH PASSWORD 'your_new_password'; # Don't forget semicolon
\q
exit

---

Debian-based Linux distributions

Prerequisites

• SMTP credentials (Gmail, ProtonMail, private Stalwart SMTP server, etc.)

System Requirements

1. Install Nginx:

   sudo add-apt-repository ppa:ondrej/nginx # Ensure correct PPA exists (Depending on your distribution and version this may be redundant)
   sudo apt update
   sudo apt install nginx-full

2. Install JREv17+

   sudo apt install openjdk-21-jre-headless # Not necessary to use OpenJDK or version 21 specifically

3. Install Database Management System:

   sudo apt install postgresql-14

4. Install Coturn:

   sudo apt install coturn

Setup Instructions

Firstly, you will have to obtain and execute the appropriate server installer - only via the terminal using sudo dpkg -i ermis-server.deb - for your individual platform; you can acquire the latest Ermis-Server installer easily from GitHub Releases.

To get the server running, follow these steps:

1. Generate an SSL Certificate
   • I highly recommend this guide on generating SSL certificates: Getting Started with SSL certificates

Important

SSL CERTS ARE LOCATED UNDER /etc/ermis-server/certs

By default, server configs point to keystore.jks server_full.pem server.key (which live under /etc/ermis-server/certs)

Tip

Alternatively, you can use the OpenSSL certificate generator located under /etc/ermis-server/certs or follow this basic guide I constructed/assembled to generate certificates through the terminal.

Or even more simply:

openssl req -x509 -days 3650 -newkey rsa:4096 \
-keyout selfsigned.key -out selfsigned.crt \
-subj "/C=US/ST=State/L=City/O=Organization/OU=Unit/CN=example.com" # CHANGE TO SOMETHING UNIQUE

openssl pkcs12 -export \
 -in selfsigned.crt \
 -inkey selfsigned.key \
 -name myalias \ # CHANGE TO SOMETHING UNIQUE
 -out selfsigned.p12 \
 -passout pass:CHANGE_IT # CHANGE TO SOMETHING UNIQUE

keytool -importkeystore \
 -deststorepass CHANGE_IT \ # CHANGE TO SOMETHING UNIQUE
 -destkeypass CHANGE_IT \ # CHANGE TO SOMETHING UNIQUE
 -destkeystore selfsigned.jks \
 -srckeystore selfsigned.p12 \
 -srcstoretype PKCS12 \
 -srcstorepass CHANGE_IT \ # CHANGE TO SOMETHING UNIQUE
 -alias myalias # CHANGE TO SOMETHING UNIQUE

2. Access the PostgreSQL shell and ensure you can access the ermis_database via ermis_admin user created during the installation process:

   psql -h 127.0.0.1 -U ermis_admin -d ermis_database

Note

If this fails, create database manually:

1. Access the PostgreSQL shell

   sudo -u postgres psql

2. Create a new user and database:

   CREATE USER ermis_admin WITH PASSWORD 'ermis_password'; -- CHANGE PASSWORD TO SOMETHING UNIQUE
   CREATE DATABASE ermis_database;
   GRANT ALL PRIVILEGES ON DATABASE ermis_database to ermis_admin;
   CREATE SCHEMA public;
   GRANT ALL ON SCHEMA public TO ermis_admin;
   \c ermis_database;
   SET search_path TO public;
   ALTER ROLE ermis_admin SET search_path TO public;
   ALTER SCHEMA public OWNER TO ermis_admin;
   exit

3. Ensure you can access the PostgreSQL database:

   psql -h 127.0.0.1 -U ermis_admin -d ermis_database

The rest of the database will be automatically configured once the server runs.

3. Change into ermis user:

   su ermis

4. Edit Configuration Files:
   Navigate to /etc/ermis-server/configs/. There, you will be faced with a wide variety of configurations that can tailor the server as well as the database however you desire. However, I recommend you don't touch anything - only specify the required fields for the server to run properly. For the most part, everything is already optimized and configured for maximum security (I explicitly declare here, though, that I won't be liable if this turns out not to be the case). Nevertheless, you are free to tinker with the settings and modify them however you like.
   • Inside /server-settings/ folder you have to specify settings related to the server - such as IP address, port, backlog, the number of threads handling user interaction, and even the encryption protocols, key exchange algorithms and cipher-suites used.
     • Specify IP address in general-settings
   • Inside /logger-settings/ folder you can configure the logging of the server - the logging style, the logger output etc.
   • Inside /emailer-settings/ folder you are required to specify essential information for the emailer to operate as intended - i.e. the username and password. Additionally, you are free to change the SMTP server and port.
     • Specify SMTP username in general-settings
   • Inside /email-templates/ folder you can customize the UI of emails sent to users, including the verification code UI.
   • Inside /donation-settings/ folder you can place your donation page HTML or redirect clients to another website. There is already a very basic and rudimental donation page integrated (it does not work all too well though).
   • Lastly /database-settings/ folder you can modify all kinds of settings related to the database and its connection with the server - e.g driver settings, pooling settings, hashing options and so forth. The setup of the database has already been discussed/addressed. In addition, you are required to enter databases credentials (username, password, address port) on the settings.
5. Configure systemd credentials:
   • Refer to /usr/share/doc/ermis-server/README.Debian

Note

You can configure systemd passwords only as root.

6. Start the Server:
   • Once configured, use the provided scripts to run the application directly through the terminal:
     1. sudo systemctl enable ermis-server.service
     2. sudo systemctl start ermis-server.service or cd /opt/ermis-server/ && ./ermis-server.sh
     3. sudo systemctl start nginx && sudo systemctl restart nginx
   • You can, in addition, view systemd logs using journalctl:

     journalctl -u ermis-server.service -e

7. Open UDP/TCP ports - if firewall is enabled:

   sudo ufw allow 80   # Required for Nginx server
   sudo ufw allow 443  # Required for Nginx server
   sudo ufw allow 9999 # Required for WebRTC signalling server
   sudo ufw allow 5439 # Optional for WebRTC STUN/TURN  server (Will default to a public STUN/TURN server if not available)
   sudo ufw allow 5440 # Optional for WebRTC STUN/TURN  server (Will default to a public STUN/TURN server if not available)
   sudo ufw allow 5551 # Required for primary messaging server

Important

If you want to open the server to the globe, you will also have to port forward all the aforementioned ports.

How to port forward