Installation¶

Once the prerequisites are in place (Ansible, Docker Swarm, and cluster initialization), you can customize the deployment of RELAYWS using Ansible variables. These options allow you to configure SSL certificate management and Nginx behavior.

Tip

Installation parameters must be configured before running the final installation command.

Important

Before the final installation of the RELAYWS environment, all target machines must be able to access the required images.

For Docker image management, refer to the documentation on Registry and Images Management for the RELAYWS environment.

Nginx Configuration¶

An Nginx service is required on each RELAYWS node to communicate with the infrastructure.

The reemo-relayws role installs and configures Nginx automatically.

The following variables can be configured:

RELAYWS_NGINX_PORT: listening port (default 8443)
RELAYWS_NGINX_SSL_VERIFY_CLIENT: enable/disable SSL verification
RELAYWS_NGINX_SSL_CLIENT_S_DN: expected DN in client certificates

SSL Certificates¶

Nginx¶

To secure communications, micro-services exchange data using mTLS, which requires certificate management.

Two modes are available:

Automatic Mode¶

By default, the reemo-relayws Ansible role automatically uses the PKI generated by the reemo-infra role. In this case, no additional configuration is needed in the inventory: the certificates are already created and available in the directory produced by reemo-infra.

Manual Configuration¶

You can also generate SSL certificates yourself for the URL: reemo_relayws.

You must then provide in the Ansible inventory the local paths to the key and certificate. They will automatically be copied into the Docker Swarm cluster by the reemo-relayws role.

Example:

relayws_manager:
    vars:
        CA_SSL_CRT_LOCALPATH: "/local/path/ca.crt"
        RELAYWS_SSL_CRT_LOCALPATH: "/local/path/reemo_relayws.crt"
        RELAYWS_SSL_KEY_LOCALPATH: "/local/path/reemo_relayws.key"
    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"

Traefik¶

All user connections go through a Traefik service. You can configure an SSL certificate to secure user access.

Three modes are available:

Default Certificate¶

By default, a self-signed certificate is automatically generated when the Traefik container is created. This mode is suitable for test environments but not recommended in production.

Local Certificate¶

You can provide a certificate and key stored on the Ansible machine. The reemo-relayws role will deploy these files on the servers running Traefik.

Inventory example:

TRAEFIK_SSL_CERTS:
    - cert_file: "/localpath/to/cert.crt"
      key_file: "/localpath/to/key.key"

Existing Certificate on the Server¶

If the certificates are already installed on the target servers, you can specify their local paths. They will then be directly mounted in the Traefik container.

Inventory example:

TRAEFIK_SSL_CERTS_REMOTE:
    - cert_file_remotepath: "/remotepath/to/cert.crt"
      key_file_remotepath: "/remotepath/to/key.key"

Pre-Installation Optimization¶

In a RELAYWS cluster with at least three servers, it is possible to optimize the connection between:

the user’s browser,
the WebSocket relay container,
and the application container.

The goal is to ensure that all traffic passes through the same Docker Swarm worker, improving performance and reducing latency (pixel stream optimization).

Preparation¶

Before configuring this optimization, you must:

define a public URL for each RELAYWS node,
associate an SSL certificate with each URL.

You can either:

use a distinct certificate for each URL,
use a Wildcard certificate covering the entire domain,
or generate a single certificate with sufficient Subject Alternative Names (SANs) to cover all node URLs.

Ansible Configuration¶

In the Ansible inventory, add for each Relayws node:

the corresponding certificate (or shared wildcard),
its hostname in the Swarm cluster,
its private IP (used by containers),
and its public URL (used by users).

Example:

relayws_manager:
    vars:
        TRAEFIK_SSL_CERTS:
            - cert_file: "/localpath/to/relayws1_cert_domain.tld.crt"
              key_file: "/localpath/to/relayws1_key_domain.tld.key"
            - cert_file: "/localpath/to/relayws2_cert_domain.tld.crt"
              key_file: "/localpath/to/relayws2_key_domain.tld.key"
            - cert_file: "/localpath/to/relayws3_cert_domain.tld.crt"
              key_file: "/localpath/to/relayws3_key_domain.tld.key"

hosts:
    relayws_manager1:
        ansible_host: "<relayws1 server IP>"
        REEMO_SWARM_NODE_HOSTNAME: "<Swarm cluster hostname>"
        REEMO_RELAYWS_PRIVATE_IP: "<private server IP>"
        REEMO_RELAYWS_PUBLIC_URL: "<public server URL>"

    relayws_manager2:
        ansible_host: "<relayws2 server IP>"
        REEMO_SWARM_NODE_HOSTNAME: "<Swarm cluster hostname>"
        REEMO_RELAYWS_PRIVATE_IP: "<private server IP>"
        REEMO_RELAYWS_PUBLIC_URL: "<public server URL>"

    relayws_manager3:
        ansible_host: "<relayws3 server IP>"
        REEMO_SWARM_NODE_HOSTNAME: "<Swarm cluster hostname>"
        REEMO_RELAYWS_PRIVATE_IP: "<private server IP>"
        REEMO_RELAYWS_PUBLIC_URL: "<public server URL>"

Final Installation¶

Once your inventory is ready, you can perform the final installation of the RELAYWS environment with the reemo-relayws Ansible role.

ansible-playbook -i inventory.yml playbooks/reemo-relayws.yml