To configure the playbook, you need to have done the following things:
You can then follow these steps inside the playbook directory:
create a directory to hold your configuration (mkdir -p inventory/host_vars/matrix.example.com where example.com is your “base domain”)
copy the sample configuration file (cp examples/vars.yml inventory/host_vars/matrix.example.com/vars.yml)
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.
copy the sample inventory hosts file (cp examples/hosts inventory/hosts)
edit the inventory hosts file (inventory/hosts) to your liking
(optional, advanced) you may wish to keep your inventory directory under version control with git or any other version-control system.
(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.
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:
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)
Storing Synapse media files on Amazon S3 or another compatible Object Storage
Configuring Element, 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, if you’ve enabled SchildiChat, a web client based on Element with some extras and tweaks
Enabling metrics and graphs (Prometheus, Grafana) for your Matrix server
Enabling synapse-usage-exporter for Synapse usage statistics
Setting up Matrix Authentication Service (Next-generation auth for Matrix, based on OAuth 2.0/OIDC)
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 Corporal (advanced)
Setting up Matrix User Verification Service (advanced)
Setting up Mautrix wsproxy for bridging Android SMS or Apple iMessage
Setting up matrix-hookshot - a bridge between Matrix and multiple project management services, such as GitHub, GitLab and JIRA.
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
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)
Setting up synapse-auto-compressor for compressing the database on Synapse homeservers
Setting up the Sliding Sync proxy for clients which require Sliding Sync support (like Element X)
Setting up Cactus Comments - a federated comment system built on Matrix
Setting up Prometheus Alertmanager integration via matrix-alertmanager-receiver
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 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)