Installation Prerequisites¶

The installation of the RELAYWS environment under Docker Swarm is carried out using the reemo-relayws Ansible role.

The RELAYWS environment consists of three main services:

Nginx: communication with the Reemo infrastructure
Traefik: entry point for Reemo Agents and users
ws-relay-server: micro-service relaying communication between a Reemo Agent and a user

Before starting, make sure your environment meets the following requirements.

Supported Operating Systems¶

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

Minimum Hardware Specifications¶

Each simultaneous connection using the RELAYWS environment consumes about 30 MB of RAM.  
1 vCPU can be shared by approximately 4 simultaneous connections.  
Size the server according to the expected number of concurrent users.  

Ansible Dependencies¶

The reemo-relayws role relies on Ansible and several collections. Install them depending on your distribution:

Red Hat / RockyLinux¶

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, it is necessary to use community.docker >= 3.10.2. If needed, force the 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 proceeding with the installation of the RELAYWS environment, Docker Swarm must be installed.

Docker Swarm¶

RELAYWS relies on a Docker Swarm cluster to dynamically deploy and manage WebSocket relay containers. The installation and initialization of Docker Swarm are therefore prerequisites before setting up the RELAYWS environment.

For installing Docker Swarm, two approaches are possible:

manual installation, performed directly on the servers,
automated installation, via the reemo-relayws Ansible role, which can install Docker and initialize the cluster with different parameters.

Minimal Inventory File¶

For a Docker Swarm installation, a minimal inventory file is required to group the nodes on which Docker Swarm will be installed and configured.

The inventory is based on the relayws_manager group. In the rest of this documentation, the inventory file will be named inventory.yml.

Example with a single server¶

relayws_manager:
    hosts:
        relayws_manager1:
            ansible_host: "10.20.0.1"

Example with a three-server cluster¶

relayws_manager:
    hosts:
        relayws_manager1:
            ansible_host: "10.20.0.1"
        relayws_manager2:
            ansible_host: "10.20.0.2"
        relayws_manager3:
            ansible_host: "10.20.0.3"

Manual Docker Swarm Installation¶

Here are the commands for a manual installation of Docker, which includes 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, you must initialize the cluster. Two options are available:

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

Automated Docker Swarm Installation¶

The reemo-relayws role can automatically install and configure Docker Swarm. The complete installation is performed automatically using the RELAYWS_INSTALL_DOCKER option:

ansible-playbook -i inventory.yml playbooks/reemo-relayws.yml --extra-vars "RELAYWS_INSTALL_DOCKER=true"

Important

The automated installation also initializes the cluster automatically.

Initialization options are detailed later in this documentation.

Docker Swarm Cluster Initialization¶

The reemo-relayws role can automatically initialize Docker Swarm using the SWARM_INIT option.

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

Several options are available for cluster initialization (example):

relayws_manager:
    vars:
        RELAYWS_SWARM_INIT_DEFAULT_ADDR_POOL: "192.168.120.0/24"
        RELAYWS_SWARM_ADVERTISE_ADDR: "eth0"
        RELAYWS_SWARM_DATA_PATH_PORT: 4789
    hosts:
        relayws_manager1:
            ansible_host: "10.20.0.1"
        relayws_manager2:
            ansible_host: "10.20.0.2"
        relayws_manager3:
            ansible_host: "10.20.0.3"

Default IP Address Pool¶

Specifies the range used by Docker Swarm for the RELAYWS environment. /24 minimum.

RELAYWS_SWARM_INIT_DEFAULT_ADDR_POOL: "192.168.120.0/24"

Advertised Address¶

In a multi-node cluster, you can specify the network interface or IP address to be advertised so that nodes can register and communicate with each other:

RELAYWS_SWARM_ADVERTISE_ADDR: "eth0"

Data Path Port¶

By default, Docker Swarm uses UDP port 4789 for overlay network communication between cluster nodes.

You can change the port used by Docker Swarm using the variables below:

RELAYWS_SWARM_DATA_PATH_PORT: 4789

Warning

In VMware NSX environments, port 4789 may conflict. Define another port at initialization of the Swarm.

Warning

Once Docker Swarm is initialized, these parameters must not be changed.