Installation Prerequisites¶

The INFRA environment under Docker Swarm is installed using the reemo-infra Ansible role.

The INFRA environment is composed of several services, mainly:

Traefik: user entrypoint
Signal: registration endpoint for Reemo Agents
Portal: user access portal
API: core of the infrastructure
DB: database

Before starting, ensure your environment meets the following conditions.

Supported operating systems¶

Ubuntu (recent LTS versions)
Red Hat Enterprise Linux
Rocky Linux

Minimum hardware specifications¶

Resources depend on the database type and the size of the architecture (number of concurrent connections). The tables below show recommended minimum values.

Case 1: Internal MySQL database¶

Environment	CPU	RAM	Disk
Infra	4	6	30G
Portal	2	4	30G
API	4	6	30G

Case 2: MySQL NDB Cluster¶

Environment	CPU	RAM	Disk
Infra	4	10	30G
Portal	2	4	30G
API	4	8	30G

Note

For an NDB cluster with more than 1000 concurrent connections, plan 8 CPU and 16 GB RAM for Infra, and 8 CPU and 14 GB RAM for API.

Case 3: External database (MySQL or PostgreSQL)¶

Environment	CPU	RAM	Disk
Infra	4	6	30G
Portal	2	4	30G
API	2	4	30G

Ansible dependencies¶

The reemo-infra role relies on Ansible and several collections. Install them according to your distribution:

Red Hat / Rocky Linux¶

yum install ansible-core
yum install -y python3-pip
pip3 install docker
ansible-galaxy collection install community.docker
ansible-galaxy collection install community.crypto

Warning

On RockyLinux 9, you must use community.docker >= 3.10.2. If needed, force an upgrade:

ansible-galaxy collection install community.docker --upgrade

Ubuntu¶

apt install ansible
apt install python3-docker
ansible-galaxy collection install community.docker
ansible-galaxy collection install community.crypto

Before installing the INFRA environment, Docker Swarm must be installed.

Docker Swarm¶

INFRA uses a Docker Swarm cluster to deploy and dynamically manage the services required by Reemo. Installing and initializing Docker Swarm is therefore a prerequisite before setting up the INFRA environment.

Two approaches are possible to install Docker Swarm:

Manual installation directly on the servers,
Automated installation via the reemo-infra Ansible role which can install Docker and initialize the cluster with various parameters.

Warning

The cluster must consist only of Manager nodes.

All nodes must be able to reach a repository to install Docker.

Minimal inventory file¶

For Docker Swarm installation, a minimal inventory file is required listing the nodes where Docker Swarm will be installed and configured.

Installation uses an Ansible inventory. It defines the architecture to deploy and declares the hosts where roles will be applied. In this documentation, the inventory file is named inventory.yml.

Three main groups exist:

infra_manager: deploys the full environment (API, Portal, DB, etc.)
portal_manager: deploys only the front part (portal and signal services)
api_manager: deploys only the API part (api, apicron, proapi, prorelayapi, etc.)

A single inventory can include one or more of these groups depending on the desired architecture.

Inventory file structure¶

The inventory file is YAML. Minimal example:

all:
    vars:
        API_LICENSE: "ewogICAg ... Uw5NXhGVDF0NFU2TkxOdjQvZU53PT0iCiAgICC9Cn0="

    infra_manager:
        hosts:
            infra_manager1:
                ansible_host: "10.0.0.1"

Example with a single server¶

all:
    vars:
        API_LICENSE: "ewogICAg ... Uw5NXhGVDF0NFU2TkxOdjQvZU53PT0iCiAgICC9Cn0="

    infra_manager:
        hosts:
            infra_manager1:
                ansible_host: "10.0.0.1"

Example with a three-server cluster¶

all:
    vars:
        API_LICENSE: "ewogICAg ... Uw5NXhGVDF0NFU2TkxOdjQvZU53PT0iCiAgICC9Cn0="

    infra_manager:
        hosts:
            infra_manager1:
                ansible_host: "10.0.0.1"
            infra_manager2:
                ansible_host: "10.0.0.2"
            infra_manager3:
                ansible_host: "10.0.0.3"

Manual Docker Swarm installation¶

Commands for manual Docker installation including Docker Swarm:

Ubuntu:

apt install docker.io python3-docker -y

RedHat:

yum install -y yum-utils
yum-config-manager --add-repo https://download.docker.com/linux/rhel/docker-ce.repo
yum install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
systemctl start docker
systemctl enable docker
yum install -y python3-pip
pip3 install docker

After installing Docker, initialize the cluster. Two options:

Manually using the Docker documentation
Using the reemo-infra Ansible role and the SWARM_INIT option. Initialization options are detailed later in this document.

Automated Docker Swarm installation¶

The reemo-infra Ansible role can install and configure Docker Swarm automatically. Run a full installation using INSTALL_DOCKER:

ansible-playbook -i inventory.yml playbooks/reemo-infra.yml --extra-vars "INSTALL_DOCKER=true"

Important

Automated installation initializes the cluster automatically.

Initialization options are detailed later in this document.

Docker Swarm cluster initialization¶

The reemo-infra Ansible role can initialize Docker Swarm automatically using SWARM_INIT.

ansible-playbook -i inventory.yml playbooks/reemo-infra.yml --extra-vars "SWARM_INIT=true"

Several options are available for cluster initialization (e.g.):

all:
    vars:
        API_SWARM_INIT_DEFAULT_ADDR_POOL: "192.168.120.0/24"
        INFRA_SWARM_INIT_DEFAULT_ADDR_POOL: "192.168.120.0/24"
        PORTAL_SWARM_INIT_DEFAULT_ADDR_POOL: "192.168.120.0/24"
        NETWORK_EXTERNAL: "10.0.6.0/24"
        NETWORK_INTERNET: "10.0.1.0/24"
        NETWORK_MYSQL: "10.0.2.0/24"
        NETWORK_PROAPI: "10.0.3.0/24"
        NETWORK_SMTP: "10.0.4.0/24"
        NETWORK_INTERNAL: "10.0.5.0/24"
        INFRA_SWARM_ADVERTISE_ADDR: "eth0"
        INFRA_SWARM_DATA_PATH_PORT: 4789
        API_SWARM_DATA_PATH_PORT: 4789
        PORTAL_SWARM_DATA_PATH_PORT: 4789
    infra_manager:
        vars:
            PORTAL_URL: "url.domain.tld"
            TRAEFIK_SSL_CERTS:
                - cert_file: "/localpath/to/cert.crt"
                  key_file: "/localpath/to/key.key"
        hosts:
            infra_manager1:
                ansible_host: "10.0.0.1"
            infra_manager2:
                ansible_host: "10.0.0.2"
            infra_manager3:
                ansible_host: "10.0.0.3"

Default IP address pool¶

During Swarm deployment, several networks are created with address ranges taken from 10.0.0.0/8 incrementally. You can define the pool used by Docker Swarm to create overlay networks. /24 minimum.

API_SWARM_INIT_DEFAULT_ADDR_POOL: "192.168.120.0/24"
INFRA_SWARM_INIT_DEFAULT_ADDR_POOL: "192.168.120.0/24"
PORTAL_SWARM_INIT_DEFAULT_ADDR_POOL: "192.168.120.0/24"

Note

You can use the same range for multiple environments (API, INFRA, PORTAL).

Explicit addressing plan¶

Specify networks used by Reemo without relying on the default pool.

all:
    vars:
        NETWORK_EXTERNAL: "10.0.6.0/24"
        NETWORK_INTERNET: "10.0.1.0/24"
        NETWORK_MYSQL: "10.0.2.0/24"
        NETWORK_PROAPI: "10.0.3.0/24"
        NETWORK_SMTP: "10.0.4.0/24"
        NETWORK_INTERNAL: "10.0.5.0/24"

Note

In MySQL Cluster, an additional network may be created: NETWORK_MYSQLNDB.

Advertised address¶

In a multi-node cluster you can specify the NIC or IP advertised to other nodes for registration and communication:

INFRA_SWARM_ADVERTISE_ADDR: "eth0"
PORTAL_SWARM_ADVERTISE_ADDR: "eth0"
API_SWARM_ADVERTISE_ADDR: "eth0"

This option is used only during cluster initialization. It can be set in the inventory or on the command line.

ansible-playbook -i inventory.yml playbooks/reemo-infra.yml \
    --limit infra_manager \
    --extra-vars "INFRA_SWARM_ADVERTISE_ADDR=eth0"

Example in an inventory:

all:
    vars:
        API_LICENSE: "ewogICAg ... Uw5NXhGVDF0NFU2TkxOdjQvZU53PT0iCiAgICC9Cn0="
    infra_manager:
        vars:
            INFRA_SWARM_ADVERTISE_ADDR: "eth0"
            PORTAL_URL: "url.domain.tld"
            TRAEFIK_SSL_CERTS:
                - cert_file: "/localpath/to/cert.crt"
                  key_file: "/localpath/to/key.key"
        hosts:
            infra_manager1:
                ansible_host: "10.0.0.1"
            infra_manager2:
                ansible_host: "10.0.0.2"
            infra_manager3:
                ansible_host: "10.0.0.3"

Data Path Port¶

By default Docker Swarm uses UDP 4789 for overlay network communication between nodes. You can change it with:

INFRA_SWARM_DATA_PATH_PORT: 4789
API_SWARM_DATA_PATH_PORT: 4789
PORTAL_SWARM_DATA_PATH_PORT: 4789

Warning

In VMware NSX environments, port 4789 can conflict. Set another port at Swarm initialization.

Warning

Once Docker Swarm is initialized, do not change its configuration (IP pools, advertise addr, ports).