matrix-docker-ansible-deploy/docs/configuring-playbook.md

Configuring the Ansible playbook

To configure the playbook, you need to have done the following things:

• have a server where Matrix services will run
• configured your DNS records
• retrieved the playbook's source code to your computer

You can then follow these steps inside the playbook directory:

1. create a directory to hold your configuration (mkdir -p inventory/host_vars/matrix.example.com where example.com is your "base domain")

2. copy the sample configuration file (cp examples/vars.yml inventory/host_vars/matrix.example.com/vars.yml)

3. edit the configuration file (inventory/host_vars/matrix.example.com/vars.yml) to your liking. You may also take a look at the various roles/*/ROLE_NAME_HERE/defaults/main.yml files and see if there's something you'd like to copy over and override in your vars.yml configuration file.

4. copy the sample inventory hosts file (cp examples/hosts inventory/hosts)

5. edit the inventory hosts file (inventory/hosts) to your liking

6. (optional, advanced) you may wish to keep your inventory directory under version control with git or any other version-control system.

7. (optional, advanced) to run Ansible against multiple servers with different sudo credentials, you can copy the sample inventory hosts yaml file for each of your hosts: (cp examples/host.yml inventory/my_host1.yml …) and use the ansible-all-hosts.sh script in the installation step.

For a basic Matrix installation, that's all you need.

For a more custom setup, see the Other configuration options below.

When you're done with all the configuration you'd like to do, continue with Installing.

Other configuration options

Additional useful services

• Setting up the Jitsi video-conferencing platform (optional)

• Setting up Etherpad (optional)

• Setting up Dynamic DNS (optional)

• Enabling metrics and graphs (Prometheus, Grafana) for your Matrix server (optional)

• Enabling synapse-usage-exporter for Synapse usage statistics (optional)

Core service adjustments

• Homeserver configuration:

  • Configuring Synapse, if you're going with the default/recommended homeserver implementation (optional)

  • Configuring Conduit, if you've switched to the Conduit homeserver implementation (optional)

  • Configuring Dendrite, if you've switched to the Dendrite homeserver implementation (optional)

• Configuring Element (optional)

• Storing Matrix media files using matrix-media-repo (optional)

• Storing Matrix media files on Amazon S3 (optional)

• Using an external PostgreSQL server (optional)

• Adjusting SSL certificate retrieval (optional, advanced)

• Serving the base domain (optional)

• Configuring the Traefik reverse-proxy (optional, advanced)

• Using your own webserver, instead of this playbook's Traefik reverse-proxy (optional, advanced)

• Adjusting TURN server configuration (optional, advanced)

Server connectivity

• Enabling Telemetry for your Matrix server (optional)

• Controlling Matrix federation (optional)

• Adjusting email-sending settings (optional)

• Setting up Hydrogen - a new lightweight Matrix client with legacy and mobile browser support (optional)

• Setting up Cinny - a web client focusing primarily on simple, elegant and secure interface (optional)

• Setting up SchildiChat - a web client based on Element with some extras and tweaks (optional)

Authentication and user-related

• Setting up Matrix Authentication Service (Next-generation auth for Matrix, based on OAuth 2.0/OIDC) (optional)

• Setting up Appservice Double Puppet (optional)

• Setting up ma1sd Identity Server (optional)

• Setting up Synapse Admin (optional)

• Setting up matrix-registration (optional)

• Setting up the REST authentication password provider module (optional, advanced)

• Setting up the Shared Secret Auth password provider module (optional, advanced)

• Setting up the LDAP authentication password provider module (optional, advanced)

• Setting up matrix-ldap-registration-proxy (optional, advanced)

• Setting up Synapse Simple Antispam (optional, advanced)

• Setting up Matrix Corporal (optional, advanced)

• Setting up Matrix User Verification Service (optional, advanced)

• Setting up Pantalaimon (E2EE aware proxy daemon) (optional, advanced)

Bridging other networks

• Setting up Mautrix Discord bridging (optional)

• Setting up Mautrix Telegram bridging (optional)

• Setting up Mautrix Slack bridging (optional)

• Setting up Mautrix Google Messages bridging (optional)

• Setting up Mautrix Whatsapp bridging (optional)

• Setting up Instagram bridging via Mautrix Meta (optional)

• Setting up Messenger bridging via Mautrix Meta (optional)

• Setting up Mautrix Google Chat bridging (optional)

• Setting up Mautrix Twitter bridging (optional)

• Setting up Mautrix Signal bridging (optional)

• Setting up Mautrix wsproxy for bridging Android SMS or Apple iMessage (optional)

• Setting up Appservice IRC bridging (optional)

• Setting up Appservice Discord bridging (optional)

• Setting up Appservice Slack bridging (optional)

• Setting up Appservice Kakaotalk bridging (optional)

• Setting up Beeper LinkedIn bridging (optional)

• Setting up matrix-hookshot - a bridge between Matrix and multiple project management services, such as GitHub, GitLab and JIRA. (optional)

• Setting up MX Puppet Slack bridging (optional)

• Setting up MX Puppet Instagram bridging (optional)

• Setting up MX Puppet Twitter bridging (optional)

• Setting up MX Puppet Discord bridging (optional)

• Setting up MX Puppet GroupMe bridging (optional)

• Setting up MX Puppet Steam bridging (optional)

• Setting up Go Skype Bridge bridging (optional)

• Setting up Email2Matrix (optional)

• Setting up Postmoogle email bridging (optional)

• Setting up Matrix SMS bridging (optional)

• Setting up Heisenbridge bouncer-style IRC bridging (optional)

• Setting up WeChat bridging (optional)

Bots

• Setting up baibot - a bot through which you can talk to various AI / Large Language Models services (OpenAI's ChatGPT and others) (optional)

• Setting up matrix-reminder-bot - a bot to remind you about stuff (optional)

• Setting up matrix-registration-bot - a bot to create and manage registration tokens to invite users (optional)

• Setting up maubot - a plugin-based Matrix bot system (optional)

• Setting up Honoroit - a helpdesk bot (optional)

• Setting up Mjolnir - a moderation tool/bot (optional)

• Setting up Draupnir - a moderation tool/bot, forked from Mjolnir and maintained by its former leader developer (optional)

• Setting up Draupnir for all/D4A - like the Draupnir bot mentioned above, but running in appservice mode and supporting multiple instances (optional)

• Setting up Buscarron - a bot you can use to send any form (HTTP POST, HTML) to a (encrypted) Matrix room (optional)

Backups

• Setting up BorgBackup - a full Matrix server backup solution, including the Postgres database (optional)

• Setting up postgres backup - a Postgres-database backup solution (note: does not include other files) (optional)

Other specialized services

• Setting up synapse-auto-compressor for compressing the database on Synapse homeservers (optional)

• Setting up the Sliding Sync proxy for clients which require Sliding Sync support (like Element X) (optional)

• Setting up the Sygnal push gateway (optional)

• Setting up the ntfy push notifications server (optional)

• Setting up Cactus Comments - a federated comment system built on Matrix (optional)

• Setting up the rageshake bug report server (optional)

• Setting up Prometheus Alertmanager integration via matrix-alertmanager-receiver (optional)

Deprecated / unmaintained / removed services

• Setting up Appservice Webhooks bridging (deprecated; the bridge's author suggests taking a look at matrix-hookshot as a replacement, which can also be installed using this playbook)

• Setting up the Dimension integration manager (unmaintained; after installing)

• Setting up Go-NEB (unmaintained; the bridge's author suggests taking a look at matrix-hookshot as a replacement, which can also be installed using this playbook)

• Setting up matrix-bot-chatgpt (unmaintained; the bridge's author suggests taking a look at baibot as a replacement, which can also be installed using this playbook)

• Setting up Mautrix Facebook bridging (deprecated in favor of the Messenger/Instagram bridge with mautrix-meta-messenger)

• Setting up Mautrix Hangouts bridging (deprecated in favor of the Google Chat bridge with mautrix-googlechat)

• Setting up Mautrix Instagram bridging (deprecated in favor of the Messenger/Instagram bridge with mautrix-meta-instagram)

• Setting up MX Puppet Skype bridging (removed; this component has been broken for a long time, so it has been removed from the playbook. Consider setting up Go Skype Bridge bridging)