podman-quadlet-cookbook/cookbooks/matrix

Podman Quadlet: Matrix

Overview

Matrix is an open, decentralised protocol for secure and interoperable communication. This cookbook runs a self-hosted Matrix homeserver using Tuwunel (a high-performance Rust-based homeserver) together with the Element Web client.

This cookbook runs the following services:

• matrix-homeserver: The Tuwunel Matrix homeserver.
• matrix-web: The Element Web browser client.
• matrix-init: One-shot first-run initialisation (creates the admin account and discovers the admin room).
• matrix-backup: Daily backup job triggered by a systemd timer.
• matrix-restore: One-shot restore job that seeds the database from the latest backup archive on first boot (if needed).
• matrix-tools: Custom OCI image (built locally from CentOS Stream 10) used by the init, backup, and restore jobs.

The homeserver uses a RocksDB database stored locally and keeps media files and backup archives on a virtiofs volume.

Prerequisites

• The traefik cookbook must be installed and running.
• A virtiofs data volume must be mounted at /var/lib/virtiofs/data/.
• Configuration files must exist before starting (see Configuration).

Configuration

Homeserver — tuwunel.env

Copy the example and adapt it to your environment:

sudo cp config/examples/tuwunel.env /etc/quadlets/matrix/tuwunel.env
sudo chmod 600 /etc/quadlets/matrix/tuwunel.env

Important: TUWUNEL_SERVER_NAME determines the Matrix identity of every user (e.g. @user:example.com). It cannot be changed after the first start. Prefer a root domain so users get clean handles, and delegate the actual HTTP traffic to a subdomain (e.g. matrix.example.com) via .well-known.

Key settings:

Variable	Description
TUWUNEL_SERVER_NAME	Matrix server name — sets user IDs (@user:<server_name>).
TUWUNEL_PORT	Port Tuwunel listens on (default: 6167).
TUWUNEL_ALLOW_REGISTRATION	Enable/disable new account registration.
TUWUNEL_REGISTRATION_TOKEN	Token required for registration (set a strong secret).
TUWUNEL_GRANT_ADMIN_TO_FIRST_USER	Automatically grants admin rights to the first registered user.
TUWUNEL_ALLOW_FEDERATION	Enable Matrix federation (disabled by default for private servers).
MATRIX_INIT_ADMIN_USER	Username for the initial admin account.
MATRIX_INIT_ADMIN_PASSWORD	Password for the initial admin account.
MATRIX_BACKUP_RETENTION	Number of daily backup archives to keep (default: 7).

Element Web — element-web/config.json

sudo mkdir -p /etc/quadlets/matrix/element-web
sudo cp config/examples/element-web/config.json /etc/quadlets/matrix/element-web/config.json

Update base_url and server_name to match your deployment:

{
    "default_server_config": {
        "m.homeserver": {
            "base_url": "https://matrix.example.com",
            "server_name": "example.com"
        }
    }
}

Traefik integration

Copy the example Traefik dynamic configuration:

sudo cp other/traefik/matrix.yaml /etc/traefik/dynamic/matrix.yaml

This configures two routes:

Hostname	Backend	Service
matrix.example.com	http://127.0.0.1:6167	Tuwunel homeserver
matrix-chat.example.com	http://127.0.0.1:8080	Element Web client

Adjust the Host() rules and entry points to match your Traefik setup.

Usage

In a separate terminal, follow the logs:

sudo make tail-logs

Install the Podman Quadlets and start Matrix:

sudo make clean install

Services start in this order:

1. matrix-tools-build.service builds the local matrix-tools image.
2. matrix-restore.service restores the database from the latest backup (only on first boot when no database exists yet and at least one backup archive is available).
3. matrix-homeserver.service starts Tuwunel.
4. matrix-web.service starts Element Web.
5. matrix-init.service runs once on first boot: registers the admin user, discovers the admin room, and writes backup credentials to /var/lib/virtiofs/data/matrix/tuwunel-backup.env.
6. matrix-backup.timer schedules the daily backup job.

Access the Element Web client through Traefik (e.g. https://matrix-chat.example.com).

Restart the matrix.target unit:

sudo systemctl restart matrix.target

Finally, remove the quadlets, their configuration and their data:

sudo make uninstall clean

Backup and restore

Backup

Backups run daily via the matrix-backup.timer. The backup job:

1. Sends the !admin server backup-database command to the Tuwunel admin room via the Matrix API (using credentials generated by matrix-init).
2. Waits for Tuwunel to write an incremental RocksDB backup to the staging area.
3. Packages the backup into a restore-ready .tar.gz archive under /var/lib/virtiofs/data/matrix/tuwunel/backup/.
4. Applies the retention policy, keeping only the last MATRIX_BACKUP_RETENTION archives.

To trigger a manual backup:

sudo systemctl start matrix-backup.service

Restore

The matrix-restore.service runs automatically before the homeserver starts if:

• No RocksDB database exists at /var/lib/quadlets/matrix/tuwunel/db/, and
• At least one .tar.gz backup archive exists under /var/lib/virtiofs/data/matrix/tuwunel/backup/.

It extracts the latest archive into the database directory, then lets the homeserver start normally.

Storage layout

Path	Contents
/var/lib/quadlets/matrix/tuwunel/db/	RocksDB database (local disk).
/var/lib/quadlets/matrix/tuwunel/backup-staging/	RocksDB online backup staging area (cleared after each backup).
/var/lib/virtiofs/data/matrix/tuwunel/media/	Uploaded media files (virtiofs).
/var/lib/virtiofs/data/matrix/tuwunel/backup/	Daily backup archives (virtiofs).
/var/lib/virtiofs/data/matrix/tuwunel-backup.env	Auto-generated backup credentials (written by matrix-init).

Integration tests

sudo make test