SSL Certificates

All user connections go through a Traefik service. The infrastructure uses SSL certificates for exposing the Portal through Traefik as well as for internal communications between platform services.

Important

It is recommended to use a different PKI for internal communications than the one used for Traefik.

Traefik

Three modes are available:

Default certificate

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

Local certificate

You can provide a certificate and key stored on the Ansible machine. The reemo-infra role deploys these files on the servers hosting Traefik.

TRAEFIK_SSL_CERTS is a list: you can declare several certificate/key pairs, for example a distinct certificate for the user portal URL and for the admin portal URL. Traefik selects the certificate matching the requested domain name.

Inventory example:

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

Certificate already present on the server

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

Like TRAEFIK_SSL_CERTS, TRAEFIK_SSL_CERTS_REMOTE accepts several certificate/key pairs.

Inventory example:

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

Internal communications

All micro-services communicate with each other using mTLS, which requires certificate management.
You have 3 options:

Default PKI

The reemo-infra Ansible role includes a complete, ready-to-use dedicated PKI. It enables a simple deployment with encrypted and authenticated internal communications.

Automatically generated CA

You can use a Certification Authority (CA) generated automatically when running the reemo-infra role.

Steps:

  1. Create a local directory on the Ansible machine, writable by the user running Ansible.

  2. Add the required options in the inventory file to enable this feature.

all:
    vars:
        LOCAL_PATH: "/opt/reemo/ssl"
        INITCA_ENABLE: "true"
    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"

When the role starts, a CA will be created automatically in this directory. The associated keys and certificates will then be exported to the Docker Swarm cluster as Secrets and mounted into the containers that need them.

Git persistence and automatic renewal

The automatically generated PKI (CA, keys, and certificates) can be stored in a Git repository. On each run of the reemo-infra role, the PKI is pulled from the repository (git pull) into LOCAL_PATH before certificates are checked, then the updated artifacts are published back (git commit and git push) after generation.

Combined with a scheduled run (CRON), this mode provides automatic certificate renewal: the CA is renewed as it approaches expiration (30 days before), and the updated PKI is published back to the repository.

This mode complements the automatically generated CA: INITCA_ENABLE must be enabled. The repository is accessed over SSH, through an SSH agent whose SSH_AUTH_SOCK environment variable is set.

Inventory example:

all:
    vars:
        LOCAL_PATH: "/opt/reemo/ssl"
        INITCA_ENABLE: "true"
        INITCA_GIT_ENABLE: "true"
        INITCA_GIT_SSH_URL: "git@example.com:your-org/reemo-pki.git"
        INITCA_GIT_BRANCH: "main"
    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"

Available options:

  • INITCA_GIT_ENABLE: enables PKI persistence in a Git repository (false by default).

  • INITCA_GIT_SSH_URL: SSH URL of the Git repository hosting the PKI.

  • INITCA_GIT_BRANCH: branch used for pull and push (main by default).

Renewing the PKI

Certificate generation and renewal are driven by the initca tag of the reemo-infra role. Re-running the role is idempotent: a certificate is regenerated only when it enters its last 30 days of validity, when the internal CA has itself been renewed (all certificates it signed are then re-issued), or when a certificate’s SAN (Subject Alternative Name, the list of host names it covers) has changed; otherwise nothing is touched.

This procedure applies to the internal PKI generated automatically (INITCA_ENABLE). To check the internal PKI and renew any certificate nearing expiry, run the role with the initca tag:

ansible-playbook -i inventory.yml playbooks/reemo-infra.yml --tags initca

When INITCA_GIT_ENABLE is set, this single command also pulls the PKI from the Git repository before the check and pushes the renewed artifacts back afterwards.

Available tags:

  • initca: the full PKI chain: git pull (if enabled), CA and per-service certificate check and renewal, then git push (if enabled).

  • initca_git: the Git steps only (pull then push), without regenerating certificates.

To make renewal fully automatic, schedule this command (for example with CRON). As the run is idempotent, it can be executed as often as you like; a daily run ensures that every certificate is renewed within the 30-day window before it expires:

# Every day at 03:00: renew the internal PKI if needed
0 3 * * * cd /path/to/ansible && ansible-playbook -i inventory.yml playbooks/reemo-infra.yml --tags initca >> /var/log/reemo-initca.log 2>&1

Note

Git persistence (INITCA_GIT_ENABLE) is what makes a scheduled renewal durable: the renewed CA and certificates are published back to the repository instead of living only on the Ansible machine. Without it, the renewed PKI is kept only in LOCAL_PATH on the host running the playbook. When INITCA_GIT_ENABLE is set, the scheduled task must also have access to an SSH agent whose SSH_AUTH_SOCK environment variable is set.

Manual configuration

You can also generate the SSL certificates yourself, then specify in the Ansible inventory the local paths of the keys and certificates. They will be copied automatically to the Docker Swarm cluster by the reemo-infra role.

For each URL, the variables follow the same pattern: <URL>_SSL_CRT_LOCALPATH and <URL>_SSL_KEY_LOCALPATH (URL name in uppercase, without the reemo_ prefix). For example, reemo_provision uses PROVISION_SSL_CRT_LOCALPATH and PROVISION_SSL_KEY_LOCALPATH.

Core URLs (always required):

  • reemo_api

  • reemo_apicron

  • reemo_portal

  • reemo_portaladmin

  • reemo_signal

  • reemo_proapi

  • reemo_prorelayapi

  • reemo_procloudapi

  • reemo_traefik

Depending on the topology and the enabled options, other URLs are required:

  • Provisioning nodes (HAProxy): reemo_provision

  • WebSocket relay: reemo_relayws

  • Database with SSL (DB_SSL_REQUIRE): reemo_db (or reemo_mariadb depending on the engine) and reemo_ndbmonitor

  • Record API (RECORDAPI_ENABLED): reemo_recordapi, reemo_recordportal, reemo_recorddb, and reemo_recordapicron

  • Appliance module (APPLIANCE_ENABLED): reemo_applianceapi and reemo_applianceportal

  • Identity (IDENTITY_ENABLED): reemo_identityapi, reemo_identityportal, and reemo_applianceidentity

  • Vault (VAULT_ENABLED): reemo_vault

  • CredentialAPI (CREDENTIAL_ENABLED): reemo_credentialapi and reemo_credentialportal

  • Wake-on-LAN (WOLAPI_ENABLE): reemo_wolapi

  • Logs (LogAPI): reemo_logapi

  • Maintenance mode: reemo_maintenance

Example:

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"
        vars:
            CA_SSL_CRT_LOCALPATH: "/local/path/ca.crt"
            API_SSL_CRT_LOCALPATH: "/local/path/reemo_api.crt"
            API_SSL_KEY_LOCALPATH: "/local/path/reemo_api.key"
            PROAPI_SSL_CRT_LOCALPATH: "/local/path/reemo_proapi.crt"
            PROAPI_SSL_KEY_LOCALPATH: "/local/path/reemo_proapi.key"
            PRORELAYAPI_SSL_CRT_LOCALPATH: "/local/path/reemo_prorelayapi.crt"
            PRORELAYAPI_SSL_KEY_LOCALPATH: "/local/path/reemo_prorelayapi.key"
            SIGNAL_SSL_CRT_LOCALPATH: "/local/path/reemo_signal.crt"
            SIGNAL_SSL_KEY_LOCALPATH: "/local/path/reemo_signal.key"
            PORTAL_SSL_CRT_LOCALPATH: "/local/path/reemo_portal.crt"
            PORTAL_SSL_KEY_LOCALPATH: "/local/path/reemo_portal.key"
            PORTALADMIN_SSL_CRT_LOCALPATH: "/local/path/reemo_portaladmin.crt"
            PORTALADMIN_SSL_KEY_LOCALPATH: "/local/path/reemo_portaladmin.key"
            PROVISION_SSL_CRT_LOCALPATH: "/local/path/reemo_provision.crt"
            PROVISION_SSL_KEY_LOCALPATH: "/local/path/reemo_provision.key"
            TRAEFIK_SSL_CERTS:
                - cert_file: "/local/path/domain.crt"
                  key_file: "/local/path/domain.key"