matrix-riot-coturn-postgres-docker-compose

A docker compose file to use the various images for which there is a Dockerfile in repos under this account.

This probably won't work out of the box.

Follow these instructions to have a functional synapse+riot+coturn+postgres composed docker service.

Build the images

matrix-synapse

This is the main Matrix homeserver, which will host the user accounts and the rooms, the uploaded media, etc...

The image exposes port 8448.

Reference: karthanistyr/matrix-synapse-docker

Arguments:

It is generally OK to leave the defaults where they exist.

• SYNAPSE_USERNAME (string): name of the unprivileged user that will run the synapse server process. This user will be created within the docker image. Default: matrix-synapse

• SYNAPSE_GROUPNAME (string): name of the user group running the synapse server process. Similarly, the group will be created within the docker image. Default: matrix-synapse

• SERVER_NAME (string): fully-qualified domain name of the machine which will serve the synapse server. There is no default, hence you must provide a value here. The hostname must be resolvable over the intended network by all potential clients.

Note that a self-signed certificate (10 years validity) with CN=$SERVER_NAME will be created automatically. You should consider replacing with a real one, e.g. Let's Encrypt.

• CONFIG_FILE (string): the name of the configuration file. Just the filename, no path. Default: synapse.config.yaml

• REPORT_STATS [yes|no]: this sets whether the synapse server will report statistics. Default: no

Example build command:

This will create an image named image_name for a server url synapse_server_url and it will be tagged latest.

docker build --build-arg SERVER_NAME=<synapse_server_url> -t <image_name> .

riot.im

This is a web client for Matrix. It's a bundle of static files destined to run on the client machine, so there is no need for a complicated web server installation to serve it.

The image exposes port 8080.

Reference: karthanistyr/riot-web-docker

Arguments:

It is generally OK to leave the defaults where they exist.

• SERVER_NAME (string): fully-qualified domain name of the machine which will serve the static files for the riot.im client. There is no default, hence you must provide a value here. The hostname must be resolvable over the intended network by all potential clients.

Note that a self-signed certificate (10 years validity) with CN=$SERVER_NAME will be created automatically. You should consider replacing with a real one, e.g. Let's Encrypt.

• RIOT_USERNAME (string): the name of the system user that will run the static files web server serving the riot.im client. It will be created within the docker image. Default: matrix-riot-web

• RIOT_GROUPNAME (string): the name of the system user group that will run the static files web server serving the riot.im client. Similarly, it will be created within the docker image. Default: matrix-riot-web

• DEFAULT_HS_HOSTNAME (string): the full hostname of the default Matrix server the riot.im client should show when brought up on a user-agent. This is not the same as SERVER_NAME unless both riot.im and the Matrix server are hosted on the same host. Default: matrix.org

• DEFAULT_HS_PORT (int): the port of the default Matrix server shown on this instance of riot.im. Default: 8448

Example build command:

This will create an image named image_name for a server url synapse_server_url and it will be tagged latest.

docker build --build-arg SERVER_NAME=<riot.im_server_name> --build-arg DEFAULT_HS_HOSTNAME=<myownmatrixserver.org> -t <image_name> .

postgresql (optional)

This is an optional backend for the synapse server. It is recommended for long-running or production instances.

This image has been customised to automatically create a database and db user for the synapse server, as described in matrix-org/synapse/blob/master/docs/postgres.rst.

The image exposes port 5432.

Reference: karthanistyr/matrix-postgres-docker

Arguments: none! (yay!)

The created db user is synapse_user and the related database is synapse.

Note: the build script will output something like The generated user password is: <64 char long password>. This is the db user's password that goes into the synapse server's configuration file.

Example build command:

This will create an image named image_name for a server url synapse_server_url and it will be tagged latest.

docker build -t <image_name> .

coturn (optional)

This is the VoIP backend server for the synapse Matrix server. It's optional if you don't plan on enabling VoIP.

The image exposes port 3478.

Reference: karthanistyr/coturn-docker

Arguments:

It is generally OK to leave the defaults where they exist.

• COTURN_VERSION (string): a coturn server release name as found at coturn/coturn/releases. Default: 4.5.0.7

• COTURN_USER (string): the name of the system user that will run the coturn server process. This user will be created within the docker container. Default: matrix-coturn

• COTURN_GROUP (string): the name of the user group running the coturn server process. Similarly it will be created within the docker container. Default: matrix-coturn

• SERVER_NAME (string): hostname of the machine which will serve the coturn server. There is no default, hence you must provide a value here. The hostname must be resolvable over the intended network by all potential clients.

Note that a self-signed certificate (10 years validity) with CN=$SERVER_NAME will be created automatically. You should consider replacing with a real one, e.g. Let's Encrypt.

• KEY_NAME (string): name of the private key file that will be auto-generated upon building the docker image. Default: matrix-coturn-key.pem

• CERT_NAME (string): name of the public X.509 certificate file that will be auto-generated upon building the docker image. Default: matrix-coturn-cert.pem

Note: during the build, the script will output something like The automatically generated secret is: <64 char long secret>. This is the automatically generated coturn secret to paste into the synapse server's configuration file if using the coturn server for VoIP support.

Example build command:

This will create an image named image_name for a server url synapse_server_url and it will be tagged latest.

docker build --build-arg SERVER_NAME=<coturn_server_hostname> -t <image_name> .

Running the docker composed service

This requires docker-compose. Check pip or your distribution packages.

The provided docker-compose file takes care of passing the parameters and the ports necessary for Matrix, Riot.im and coturn to work.

Note: if you aren't using the coturn image, remove mentions to it in the docker-compose.yaml file.

Note: the postgres configuration in the matrix-synapse image isn't operational out of the box yet and requires a manual step if you want to use it.

Example run command:

docker-compose up -d

Optional manual steps

After all the images are built, there are a few manual steps to be done before everything runs together.

coturn VoIP: configure the coturn server within the synapse configuration file

Note that for any of this to work, the coturn server must present a certificate that the synapse server must trust. This probably requires acquiring a proper TLS certificate from a trusted CA.

1. Get the coturn server's shared secret from the newly built coturn image. It is located in the coturn server's configuration file (within a folder name /data at the root of the image's filesystem). Alternatively, fetch it from the stdout output of the build script.

2. Edit the synapse configuration file (also located at /data at the root of the synapse image), find and replace the following lines (don't forget to replace <coturn_server_hostname> and <coturn_server_secret>):

   turn_uris: ["turn:<coturn_server_hostname>:3478?transport=udp", "turn:<coturn_server_hostname>:3478?transport=tcp"]

   turn_shared_secret: "<coturn_server_secret>"

Configuring postgres support for matrix-synapse

You must edit the synapse configuration file.

If using the above-mentioned postgresql image, please take note of the hardcoded username and db name, and the automatically generated db user password (see postgresql).

Step-by-step instructions can be found here: matrix-org/synapse/blob/master/docs/postgres.rst