configuring-playbook.md

Configuring the playbook

^{⚡️Quick start | Prerequisites > Configuring your DNS server > Getting the playbook > Configuring the playbook > Installing}

To configure the Ansible 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

Core service adjustments

• Homeserver configuration:

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

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

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

• Server components:

  • Using an external PostgreSQL server

  • Adjusting TURN server configuration (advanced)

  • Configuring the Traefik reverse-proxy (advanced)

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

  • Adjusting SSL certificate retrieval (advanced)

  • Adjusting email-sending settings

  • Setting up ma1sd Identity Server

  • Setting up Dynamic DNS

• Server connectivity:

  • Enabling Telemetry for your Matrix server

  • Controlling Matrix federation

• Serving the base domain

Clients

Web clients for Matrix that you can host on your own domains.

• Configuring Element Web, if you're going with the default/recommended client

• Setting up Hydrogen, if you've enabled Hydrogen, a lightweight Matrix client with legacy and mobile browser support

• Setting up Cinny, if you've enabled Cinny, a web client focusing primarily on simple, elegant and secure interface

• Setting up SchildiChat Web, if you've enabled SchildiChat Web, a web client based on Element Web with some extras and tweaks

Authentication and user-related

Extend and modify how users are authenticated on your homeserver.

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

• Setting up Appservice Double Puppet

• Setting up Synapse Admin

• Setting up matrix-registration

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

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

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

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

• Setting up Synapse Simple Antispam (advanced)

• Setting up Matrix User Verification Service (advanced)

File Storage

Use alternative file storage to the default media_store folder.

• Storing Matrix media files on Amazon S3 with Goofys

• Storing Synapse media files on Amazon S3 or another compatible Object Storage

• Storing Matrix media files using matrix-media-repo

Bridging other networks

Bridges can be used to connect your Matrix installation with third-party communication networks.

• Setting up Mautrix Discord bridging

• Setting up Mautrix Telegram bridging

• Setting up Mautrix Slack bridging

• Setting up Mautrix Google Messages bridging

• Setting up Mautrix Whatsapp bridging

• Setting up Instagram bridging via Mautrix Meta

• Setting up Messenger bridging via Mautrix Meta

• Setting up Mautrix Google Chat bridging

• Setting up Mautrix Twitter bridging

• Setting up Mautrix Signal bridging

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

• Setting up Appservice IRC bridging

• Setting up Appservice Discord bridging

• Setting up Appservice Slack bridging

• Setting up Appservice Kakaotalk bridging

• Setting up Beeper LinkedIn bridging

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

• Setting up MX Puppet Slack bridging

• Setting up MX Puppet Instagram bridging

• Setting up MX Puppet Twitter bridging

• Setting up MX Puppet Discord bridging

• Setting up MX Puppet GroupMe bridging

• Setting up MX Puppet Steam bridging

• Setting up Go Skype Bridge bridging

• Setting up Email2Matrix

• Setting up Postmoogle email bridging

• Setting up Matrix SMS bridging

• Setting up Heisenbridge bouncer-style IRC bridging

• Setting up WeChat bridging

Bots

Bots provide various additional functionality to your installation.

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

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

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

• Setting up maubot - a plugin-based Matrix bot system

• Setting up Honoroit - a helpdesk bot

• Setting up Mjolnir - a moderation tool/bot

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

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

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

Administration

Services that help you in administrating and monitoring your Matrix installation.

• Setting up Prometheus Alertmanager integration via matrix-alertmanager-receiver

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

• Enabling metrics and graphs for NginX logs

• Setting up the rageshake bug report server

• Enabling synapse-usage-exporter for Synapse usage statistics

• Backups:

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

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

Other specialized services

Various services that don't fit any other categories.

• Setting up Synapse Auto Invite Accept

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

• Setting up Matrix Corporal (advanced)

• Setting up Etherpad

• Setting up the Jitsi video-conferencing platform

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

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

• Setting up the Sygnal push gateway

• Setting up the ntfy push notifications server

Deprecated / unmaintained / removed services

Note: since a deprecated or unmaintained service will not be updated, its bug or vulnerability will be unlikely to get patched. It is recommended to migrate from the service to an alternative if any, and make sure to do your own research before you decide to keep it running nonetheless.

• Setting up the Sliding Sync proxy for clients which require Sliding Sync support (like old Element X versions, before it got switched to Simplified Sliding Sync)

• 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)