Matrix Docker Compose

RU Readme.md

A ready-to-use configuration for deploying a Matrix server (Synapse) with a web client (Element) and a Coturn TURN server (for video calls) using Docker Compose.

This project is not intended to demonstrate best practices, but rather to help you quickly deploy and familiarize yourself with Matrix, or to perform some tasks and then destroy it.

Prerequisites

Before you start, make sure you have the following:

1. A server with a public IP address.
2. Docker and Docker Compose installed on the server.
3. A domain name (SYNAPSE_SERVER_NAME) and a TURN domain (COTURN_REALM) pointed to your server's IP address via DNS A records. This is required for Caddy to issue SSL certificates and for federation to work correctly.

Deployment

Deployment is fully automated via GitHub Actions (.github/workflows/deploy.yml).

On the first run, a homeserver.yaml file will be automatically generated on the server with all settings taken from the repository's secrets. Subsequent deployments will not overwrite this file.

Required Secrets

For deployment, add the following secrets in Settings -> Secrets and variables -> Actions:

Server Connection

Variable	Description
SSH_HOST	IP address or domain name of your server.
SSH_USER	Username for the SSH connection.
SSH_PRIVATE_KEY	Your private SSH key for authentication.
SSH_PORT	SSH port of your server (e.g., 22).
PROJECT_PATH	Absolute path to the project directory on the server.

Service Configuration

Variable	Description
SYNAPSE_SERVER_NAME	The main domain of your Matrix server (e.g., mtrx.example.com).
POSTGRES_PASSWORD	A strong password for the PostgreSQL database user.
COTURN_IP	The public IP address of your server for Coturn.
COTURN_REALM	The domain for the TURN server (e.g., turn.mtrx.example.com).
COTURN_SECRET	A secret key for authentication on the TURN server.

User Management

To add new users, use the .github/workflows/add-user.yml workflow.

1. Go to the Actions section of your repository.
2. In the list on the left, select Add Matrix User.
3. Click Run workflow.
4. Enter the username, password, and specify if the user should be an administrator (true/false).
5. Run the workflow.

Complete Removal

To completely remove the project from the server (including all data, docker volumes, and files), use the .github/workflows/destroy.yml workflow.

Warning: This action is irreversible.

1. Go to the Actions section of your repository.
2. In the list on the left, select Destroy Project.
3. Click Run workflow.
4. To confirm, type destroy in the corresponding field.
5. Run the workflow.