federation-airgap

Example airgap deployment of Rocket.Chat federation with Synapse

This document shows how to use the script, for how Rocket.Chat federation, refer to DESIGN.md and for manual process, read MANUAL.md

This document also focuses on podman instead of docker (the script also uses podman & podman-compose)

Prerequisites

1. Run the following to enable the reverse proxy (nginx) to bind to port 80 (and 443).

sudo sysctl -w net.ipv4.ip_unprivileged_port_start=80

2. Your own CA signed certificates

Matrix federation requires TLS. So you must have your own CA and a CA signed certificate.

This certificate must have two SANs, one for your rocket.chat instance, another with matrix subdomain (or whatever you choose the subdomain to be, more on that later).

Example extension file

authorityKeyIdentifier=keyid,issuer
basicConstraints=CA:FALSE
keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
subjectAltName = @alt_names

[alt_names]
DNS.1 = example.com
DNS.2 = matrix.example.com

You can put the root domain for common name in the csr.

3. podman installed
4. Optionally podman-compose installed

List of images (default, can vary depending on cli arguments)

• docker.io/bitnami/mongodb:5.0
• docker.io/rocketchat/rocket.chat:6.0.0
• docker.io/matrixdotorg/synapse:v1.78.0
• docker.io/nginx:latest
• docker.io/redis:latest
• docker.io/postgres:14

tl;dr;

1. Clone this repo, move it to your private system
2. Make sure you have the images added to storage in advance
3. Change into the directory and run the following command

bash ./install.sh \
	--ca-certificate <path to your CA cert> \
	--certificate <CA signed cert for your domain[s]> \
	--private-key <private key for your certificate> \
	--domain <enter your rocket.chat domain>

Add --podman-compose to use podman-compose instead of the podman run commands directly.

I don't recommend using podman-compose right now, as it is not 1:1 with docker compose and has its quirks.

Now wait for it to complete.

Script help

You can run --help to get all the available options. You should see something like the following

--ca-certificate         path (relative or absolute) to your CA certificate
--domain                 your room domain, or on which domain your Rocket.Chat instance will live
--certificate            path to your CA signed certificate
--private-key            path to your certificate's private key

[Optional]

--ca-private-key        private key of your CA, used to auto generate a certificate (don't pass certificate or private key if using this)
--matrix-subdomain      subdomain on which your matrix server will live (defaults to "matrix")
--mongo-version         mongodb version (defaults to 5.0)
--rocketchat-version    defaults to 6.0.0
--synapse-version       defaults to v1.78.0
--podman-compose        use podman-compose instead of podman commands

Gotcha

--ca-certificate is mandatory argument. You can either pass an already signed certificate and private key with --certificate and --private-key respectively or have it generate that for you by adding --ca-private-key pointing to your CA's private key and removing the --certificate and --private-key options.

Internal details

./conf directory

This directory holds all the templates for different component configuration.

• registration.yaml.tpl is the matrix application service registration file. It is shared between synapse and rocket.chat containers.
• homeserver.append.yaml.tpl is the "append" file, i.e. this is not the complete synapse config file. That is generated by synapse initially, this file contains what will be eventually appended to the generated config (in other words some Rocket.Chat specific configurations), in template format.
• nginx.conf.tpl templated config for nginx.
• podman-compose.yaml.tpl podman-compose service definition file.

Environment variables

You can change certain aspects with various environment variables.

Container names

You can change individual container names by setting the following environment variables prior to running the script

Component	Variable	Default
Rocket.Chat	ROCKETCHAT_CONTAINER	rocketchat
MongoDB	MONGO_CONTAINER	mongodb
Matrix (Synapse)	MATRIX_CONTAINER	matrix
Redis	REDIS_CONTAINER	redis
PostgreSQL	POSTGRES_CONTAINER	postgres
Proxy (Nginx)	PROXY_CONTAINER	proxy

Images

If you've already pulled images but with different tags than mentioned above, you can override them with the following environment variables

Component	Variable
Rocket.Chat	ROCKETCHAT_IMAGE
MongoDB	MONGO_IMAGE
Synapse	SYNAPSE_IMAGE
Redis	REDIS_IMAGE
PostgreSQL	POSTGRES_IMAGE
Nginx	NGINX_IMAGE

Persistence

If using podman cli, the script creates some default volumes.

• For postgres - rocketchat_matrix_postgres
• For synapse - data directory in your current folder
• For mongo - rocketchat_mongodb

If using podman-compose, volume names are in the generated podman-compose file (./conf/podman-compose.yaml) and their lifecycle is handled by podman-compose.

The CA certificate is mounted on the matrix container so that it can verify the certificates of other homeservers on the same network and under the same PKI.

Network

Creates a network rocketchat if using podman cli. podman-compose creates its own default project-wise network.

SELinux

Nothing specific here, the bind mounts are using the z opt to correctly label the files/directories.

podman-compose

The --podman-compose argument uses podman-compose tool instead of the podman run cli. The argument generates two files, a .env file, and a podman-compose.yaml file, both in the conf directory.

If you want to manually start of stop the containers started with podman-compose

# or (cd conf; podman-compose -f podman-compose.yaml down)
podman-compose -f conf/podman-compose.yaml down

or

# install.sh starts the containers in order automatically
# or (cd conf; podman-compose -f podman-compose.yaml up -d)
podman-compose -f conf/podman-compose.yaml up -d