2018-08-15 07:19:31 +00:00
# Configuring the Ansible playbook
2018-08-08 07:07:02 +00:00
2019-03-10 15:02:17 +00:00
To configure the playbook, you need to have done the following things:
2018-08-08 07:07:02 +00:00
2019-03-10 15:02:17 +00:00
- have a server where Matrix services will run
- [configured your DNS records ](configuring-dns.md )
- [retrieved the playbook's source code ](getting-the-playbook.md ) to your computer
You can then follow these steps inside the playbook directory:
2018-08-08 07:07:02 +00:00
2021-03-06 18:35:12 +00:00
1. create a directory to hold your configuration (`mkdir inventory/host_vars/matrix.< your-domain > `)
2018-08-08 07:07:02 +00:00
2021-03-06 18:35:12 +00:00
1. copy the sample configuration file (`cp examples/vars.yml inventory/host_vars/matrix.< your-domain > /vars.yml`)
2018-08-08 07:07:02 +00:00
2023-04-27 05:12:09 +00:00
1. edit the configuration file (`inventory/host_vars/matrix.< your-domain > /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.
2018-08-08 07:07:02 +00:00
2021-03-06 18:35:12 +00:00
1. copy the sample inventory hosts file (`cp examples/hosts inventory/hosts`)
2018-08-08 07:07:02 +00:00
2021-03-06 18:35:12 +00:00
1. edit the inventory hosts file (`inventory/hosts`) to your liking
2018-08-08 07:07:02 +00:00
2022-07-26 13:34:55 +00:00
1. (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` ](../inventory/scripts/ansible-all-hosts.sh ) script [in the installation step ](installing.md ).
2018-08-08 07:07:02 +00:00
For a basic Matrix installation, that's all you need.
For a more custom setup, see the [Other configuration options ](#other-configuration-options ) below.
When you're done with all the configuration you'd like to do, continue with [Installing ](installing.md ).
## Other configuration options
2019-04-19 06:54:18 +00:00
### Additional useful services
2018-11-01 16:21:38 +00:00
2023-08-16 06:17:32 +00:00
- [Setting up the Dimension Integration Manager ](configuring-playbook-dimension.md ) (optional; [unmaintained ](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/2806#issuecomment-1673559299 ); after [installing ](installing.md ))
2018-10-25 15:02:04 +00:00
2020-03-24 16:26:52 +00:00
- [Setting up the Jitsi video-conferencing platform ](configuring-playbook-jitsi.md ) (optional)
2022-10-15 20:17:58 +00:00
- [Setting up Etherpad ](configuring-playbook-etherpad.md ) (optional)
2021-01-26 15:19:28 +00:00
- [Setting up Dynamic DNS ](configuring-playbook-dynamic-dns.md ) (optional)
2019-04-19 06:54:18 +00:00
2021-02-12 12:02:53 +00:00
- [Enabling metrics and graphs (Prometheus, Grafana) for your Matrix server ](configuring-playbook-prometheus-grafana.md ) (optional)
2019-04-19 06:54:18 +00:00
### Core service adjustments
2018-08-14 11:11:41 +00:00
2022-10-27 06:48:49 +00:00
- Homeserver configuration:
- [Configuring Synapse ](configuring-playbook-synapse.md ), if you're going with the default/recommended homeserver implementation (optional)
- [Configuring Conduit ](configuring-playbook-conduit.md ), if you've switched to the [Conduit ](https://conduit.rs ) homeserver implementation (optional)
2019-08-22 06:49:22 +00:00
2022-11-20 08:11:21 +00:00
- [Configuring Dendrite ](configuring-playbook-dendrite.md ), if you've switched to the [Dendrite ](https://matrix-org.github.io/dendrite ) homeserver implementation (optional)
2020-07-17 08:31:20 +00:00
- [Configuring Element ](configuring-playbook-client-element.md ) (optional)
2019-08-25 07:37:05 +00:00
2023-07-17 19:37:53 +00:00
- [Storing Matrix media files using matrix-media-repo ](configuring-playbook-matrix-media-repo.md ) (optional)
2018-08-08 07:10:16 +00:00
- [Storing Matrix media files on Amazon S3 ](configuring-playbook-s3.md ) (optional)
2018-08-08 07:07:02 +00:00
- [Using an external PostgreSQL server ](configuring-playbook-external-postgres.md ) (optional)
2018-12-23 09:00:12 +00:00
- [Adjusting SSL certificate retrieval ](configuring-playbook-ssl-certificates.md ) (optional, advanced)
2019-03-12 20:27:18 +00:00
- [Serving your base domain using this playbook's nginx server ](configuring-playbook-base-domain-serving.md ) (optional)
2023-02-26 14:14:05 +00:00
- [Configure the Traefik reverse-proxy ](configuring-playbook-traefik.md ) (optional, advanced)
2019-04-17 11:42:09 +00:00
2023-02-26 14:14:05 +00:00
- (Deprecated) [Configure the Nginx reverse-proxy ](configuring-playbook-nginx.md ) (optional, advanced)
- [Using your own webserver, instead of this playbook's default reverse-proxy ](configuring-playbook-own-webserver.md ) (optional, advanced)
2018-08-17 06:02:12 +00:00
2019-04-19 06:57:41 +00:00
- [Adjusting TURN server configuration ](configuring-playbook-turn.md ) (optional, advanced)
2019-04-19 06:54:18 +00:00
### Server connectivity
- [Enabling Telemetry for your Matrix server ](configuring-playbook-telemetry.md ) (optional)
- [Controlling Matrix federation ](configuring-playbook-federation.md ) (optional)
- [Adjusting email-sending settings ](configuring-playbook-email.md ) (optional)
2021-05-21 10:50:45 +00:00
- [Setting up Hydrogen ](configuring-playbook-client-hydrogen.md ) - a new lightweight matrix client with legacy and mobile browser support (optional)
2022-03-17 15:58:59 +00:00
2022-01-05 16:33:21 +00:00
- [Setting up Cinny ](configuring-playbook-client-cinny.md ) - a web client focusing primarily on simple, elegant and secure interface (optional)
2021-05-21 10:50:45 +00:00
2019-04-19 06:54:18 +00:00
### Authentication and user-related
2022-03-17 15:58:59 +00:00
- [Setting up an ma1sd Identity Server ](configuring-playbook-ma1sd.md ) (optional)
2020-07-22 05:10:26 +00:00
- [Setting up Synapse Admin ](configuring-playbook-synapse-admin.md ) (optional)
2020-09-01 10:46:05 +00:00
- [Setting up matrix-registration ](configuring-playbook-matrix-registration.md ) (optional)
2018-11-26 05:23:42 +00:00
- [Setting up the REST authentication password provider module ](configuring-playbook-rest-auth.md ) (optional, advanced)
2018-08-20 14:11:55 +00:00
2018-11-26 05:23:42 +00:00
- [Setting up the Shared Secret Auth password provider module ](configuring-playbook-shared-secret-auth.md ) (optional, advanced)
2018-08-21 10:34:34 +00:00
2018-11-28 09:21:03 +00:00
- [Setting up the LDAP password provider module ](configuring-playbook-ldap-auth.md ) (optional, advanced)
2022-09-16 17:15:33 +00:00
- [Setting up the ldap-registration-proxy ](configuring-playbook-matrix-ldap-registration-proxy.md ) (optional, advanced)
2019-09-09 05:13:06 +00:00
- [Setting up Synapse Simple Antispam ](configuring-playbook-synapse-simple-antispam.md ) (optional, advanced)
2018-11-26 05:23:42 +00:00
- [Setting up Matrix Corporal ](configuring-playbook-matrix-corporal.md ) (optional, advanced)
2018-09-07 20:35:04 +00:00
2023-02-10 14:08:55 +00:00
- [Matrix User Verification Service ](configuring-playbook-user-verification-service.md ) (optional, advanced)
2023-02-10 12:26:38 +00:00
2019-04-19 06:54:18 +00:00
### Bridging other networks
2022-07-22 14:55:44 +00:00
- [Setting up Mautrix Discord bridging ](configuring-playbook-bridge-mautrix-discord.md ) (optional)
2018-10-26 16:44:58 +00:00
- [Setting up Mautrix Telegram bridging ](configuring-playbook-bridge-mautrix-telegram.md ) (optional)
2023-01-11 08:38:54 +00:00
- [Setting up Mautrix Slack bridging ](configuring-playbook-bridge-mautrix-slack.md ) (optional)
2023-07-21 11:33:52 +00:00
- [Setting up Mautrix Google Messages bridging ](configuring-playbook-bridge-mautrix-gmessages.md ) (optional)
2018-11-03 23:30:17 +00:00
- [Setting up Mautrix Whatsapp bridging ](configuring-playbook-bridge-mautrix-whatsapp.md ) (optional)
2019-01-31 05:37:23 +00:00
2019-05-08 14:33:09 +00:00
- [Setting up Mautrix Facebook bridging ](configuring-playbook-bridge-mautrix-facebook.md ) (optional)
2019-08-21 04:24:58 +00:00
- [Setting up Mautrix Hangouts bridging ](configuring-playbook-bridge-mautrix-hangouts.md ) (optional)
2021-10-12 11:45:04 +00:00
- [Setting up Mautrix Google Chat bridging ](configuring-playbook-bridge-mautrix-googlechat.md ) (optional)
2021-02-19 18:37:36 +00:00
- [Setting up Mautrix Instagram bridging ](configuring-playbook-bridge-mautrix-instagram.md ) (optional)
2021-04-11 06:45:27 +00:00
- [Setting up Mautrix Twitter bridging ](configuring-playbook-bridge-mautrix-twitter.md ) (optional)
2020-10-25 17:44:19 +00:00
- [Setting up Mautrix Signal bridging ](configuring-playbook-bridge-mautrix-signal.md ) (optional)
2023-08-23 12:11:08 +00:00
- [Setting up Mautrix wsproxy for bridging Android SMS or Apple iMessage ](configuring-playbook-bridge-mautrix-wsproxy.md ) (optional)
2019-01-31 05:37:23 +00:00
- [Setting up Appservice IRC bridging ](configuring-playbook-bridge-appservice-irc.md ) (optional)
2019-03-03 17:22:52 +00:00
- [Setting up Appservice Discord bridging ](configuring-playbook-bridge-appservice-discord.md ) (optional)
2019-06-10 14:52:48 +00:00
- [Setting up Appservice Slack bridging ](configuring-playbook-bridge-appservice-slack.md ) (optional)
2019-08-21 04:34:20 +00:00
2020-01-14 14:02:37 +00:00
- [Setting up Appservice Webhooks bridging ](configuring-playbook-bridge-appservice-webhooks.md ) (optional)
2022-07-25 11:34:21 +00:00
- [Setting up Appservice Kakaotalk bridging ](configuring-playbook-bridge-appservice-kakaotalk.md ) (optional)
- [Setting up Beeper LinkedIn bridging ](configuring-playbook-bridge-beeper-linkedin.md ) (optional)
2022-02-01 12:07:43 +00:00
- [Setting up matrix-hookshot ](configuring-playbook-bridge-hookshot.md ) - a bridge between Matrix and multiple project management services, such as [GitHub ](https://github.com ), [GitLab ](https://about.gitlab.com ) and [JIRA ](https://www.atlassian.com/software/jira ). (optional)
2022-07-15 16:49:47 +00:00
- ~~[Setting up MX Puppet Skype bridging](configuring-playbook-bridge-mx-puppet-skype.md)~~ (optional) - this component has been broken for a long time, so it has been removed from the playbook. Consider [Setting up Go Skype Bridge bridging ](configuring-playbook-bridge-go-skype-bridge.md )
2020-04-09 06:33:30 +00:00
2020-04-23 15:03:36 +00:00
- [Setting up MX Puppet Slack bridging ](configuring-playbook-bridge-mx-puppet-slack.md ) (optional)
2020-06-30 14:51:56 +00:00
- [Setting up MX Puppet Instagram bridging ](configuring-playbook-bridge-mx-puppet-instagram.md ) (optional)
- [Setting up MX Puppet Twitter bridging ](configuring-playbook-bridge-mx-puppet-twitter.md ) (optional)
2020-07-01 16:01:14 +00:00
- [Setting up MX Puppet Discord bridging ](configuring-playbook-bridge-mx-puppet-discord.md ) (optional)
2021-02-13 15:55:54 +00:00
- [Setting up MX Puppet GroupMe bridging ](configuring-playbook-bridge-mx-puppet-groupme.md ) (optional)
2020-07-03 09:10:57 +00:00
- [Setting up MX Puppet Steam bridging ](configuring-playbook-bridge-mx-puppet-steam.md ) (optional)
2022-06-12 21:29:43 +00:00
- [Setting up Go Skype Bridge bridging ](configuring-playbook-bridge-go-skype-bridge.md ) (optional)
2019-08-05 10:06:49 +00:00
- [Setting up Email2Matrix ](configuring-playbook-email2matrix.md ) (optional)
2020-05-23 11:14:24 +00:00
2022-08-23 11:16:07 +00:00
- [Setting up Postmoogle email bridging ](configuring-playbook-bot-postmoogle.md ) (optional)
2020-09-01 10:47:58 +00:00
- [Setting up Matrix SMS bridging ](configuring-playbook-bridge-matrix-bridge-sms.md ) (optional)
2020-07-20 11:13:08 +00:00
2021-05-12 12:24:39 +00:00
- [Setting up Heisenbridge bouncer-style IRC bridging ](configuring-playbook-bridge-heisenbridge.md ) (optional)
2020-07-20 11:13:08 +00:00
### Bots
2023-01-10 15:31:21 +00:00
- [Setting up matrix-bot-chatgpt ](configuring-playbook-bot-chatgpt.md ) - a bot through which you can talk to the [ChatGPT ](https://openai.com/blog/chatgpt/ ) model(optional)
2023-01-10 15:22:54 +00:00
2021-04-03 07:52:35 +00:00
- [Setting up matrix-reminder-bot ](configuring-playbook-bot-matrix-reminder-bot.md ) - a bot to remind you about stuff (optional)
2021-03-16 05:54:26 +00:00
2022-04-25 07:37:35 +00:00
- [Setting up matrix-registration-bot ](configuring-playbook-bot-matrix-registration-bot.md ) - a bot to create and manage registration tokens to invite users (optional)
2022-07-11 11:28:23 +00:00
- [Setting up maubot ](configuring-playbook-bot-maubot.md ) - a plugin-based Matrix bot system (optional)
2022-01-06 18:30:10 +00:00
- [Setting up honoroit ](configuring-playbook-bot-honoroit.md ) - a helpdesk bot (optional)
2021-04-03 07:52:35 +00:00
- [Setting up Go-NEB ](configuring-playbook-bot-go-neb.md ) - an extensible multifunctional bot (optional)
- [Setting up Mjolnir ](configuring-playbook-bot-mjolnir.md ) - a moderation tool/bot (optional)
2021-03-20 11:31:34 +00:00
2023-02-10 12:26:38 +00:00
- [Setting up Draupnir ](configuring-playbook-bot-draupnir.md ) - a moderation tool/bot, forked from Mjolnir and maintained by its former leader developer (optional)
2023-02-10 09:52:25 +00:00
2022-04-25 07:37:35 +00:00
- [Setting up Buscarron ](configuring-playbook-bot-buscarron.md ) - a bot you can use to send any form (HTTP POST, HTML) to a (encrypted) Matrix room (optional)
2021-03-20 11:31:34 +00:00
2022-04-19 16:29:41 +00:00
### Backups
- [Setting up borg backup ](configuring-playbook-backup-borg.md ) - a full Matrix server backup solution, including the Postgres database (optional)
- [Setting up postgres backup ](configuring-playbook-postgres-backup.md ) - a Postgres-database backup solution (note: does not include other files) (optional)
2021-03-20 11:31:34 +00:00
### Other specialized services
2023-03-12 08:55:08 +00:00
- [Setting up synapse-auto-compressor ](configuring-playbook-synapse-auto-compressor.md ) for compressing the database on Synapse homeservers (optional)
2023-03-07 10:22:04 +00:00
- [Setting up the Sliding Sync Proxy ](configuring-playbook-sliding-sync-proxy.md ) for clients which require Sliding Sync support (like Element X) (optional)
2021-03-20 11:31:34 +00:00
- [Setting up the Sygnal push gateway ](configuring-playbook-sygnal.md ) (optional)
2022-06-27 21:20:02 +00:00
- [Setting up the ntfy push notifications server ](configuring-playbook-ntfy.md ) (optional)
2022-09-16 17:15:33 +00:00
2022-09-09 11:37:52 +00:00
- [Setting up a Cactus Comments server ](configuring-playbook-cactus-comments.md ) - a federated comment system built on Matrix (optional)
2023-02-25 12:00:42 +00:00
- [Setting up the Rageshake bug report server ](configuring-playbook-rageshake.md ) (optional)