pub-solar/matrix-docker-ansible-deploy
5
0
Fork 0
Code Issues Pull requests Packages Projects Releases Wiki Activity
matrix-docker-ansible-deploy/README.md

143 lines
13 KiB
Markdown
Raw Normal View History

Add donation and support room badges
2020-12-01 13:24:07 +00:00
[![Support room on Matrix](https://img.shields.io/matrix/matrix-docker-ansible-deploy:devture.com.svg?label=%23matrix-docker-ansible-deploy%3Adevture.com&logo=matrix&style=for-the-badge&server_fqdn=matrix.devture.com)](https://matrix.to/#/#matrix-docker-ansible-deploy:devture.com) [![donate](https://liberapay.com/assets/widgets/donate.svg)](https://liberapay.com/s.pantaleev/donate)
Initial commit
2017-07-31 20:07:30 +00:00
# Matrix (An open network for secure, decentralized communication) server setup using Ansible and Docker
## Purpose
Make README more tidy
2021-01-24 08:04:30 +00:00
This [Ansible](https://www.ansible.com/) playbook is meant to help you run your own [Matrix](http://matrix.org/) homeserver, along with the [various services](#supported-services) related to that.
Initial commit
2017-07-31 20:07:30 +00:00
Make README more tidy
2021-01-24 08:04:30 +00:00
That is, it lets you join the Matrix network using your own `@<username>:<your-domain>` identifier, all hosted on your own server (see [prerequisites](docs/prerequisites.md)).
We run all services in [Docker](https://www.docker.com/) containers (see [the container images we use](docs/container-images.md)), which lets us have a predictable and up-to-date setup, across multiple supported distros (see [prerequisites](docs/prerequisites.md)) and [architectures](docs/alternative-architectures.md) (x86/amd64 being recommended).
[Installation](docs/README.md) (upgrades) and some maintenance tasks are automated using [Ansible](https://www.ansible.com/) (see [our Ansible guide](docs/ansible.md)).
## Supported services
Initial commit
2017-07-31 20:07:30 +00:00
Using this playbook, you can get the following services configured on your server:
Update README and changelog
2019-05-21 02:04:58 +00:00
- (optional, default) a [Synapse](https://github.com/matrix-org/synapse) homeserver - storing your data and managing your presence in the [Matrix](http://matrix.org/) network
Initial commit
2017-07-31 20:07:30 +00:00
Make roles more independent of one another With this change, the following roles are now only dependent on the minimal `matrix-base` role: - `matrix-corporal` - `matrix-coturn` - `matrix-mailer` - `matrix-mxisd` - `matrix-postgres` - `matrix-riot-web` - `matrix-synapse` The `matrix-nginx-proxy` role still does too much and remains dependent on the others. Wiring up the various (now-independent) roles happens via a glue variables file (`group_vars/matrix-servers`). It's triggered for all hosts in the `matrix-servers` group. According to Ansible's rules of priority, we have the following chain of inclusion/overriding now: - role defaults (mostly empty or good for independent usage) - playbook glue variables (`group_vars/matrix-servers`) - inventory host variables (`inventory/host_vars/matrix.<your-domain>`) All roles default to enabling their main component (e.g. `matrix_mxisd_enabled: true`, `matrix_riot_web_enabled: true`). Reasoning: if a role is included in a playbook (especially separately, in another playbook), it should "work" by default. Our playbook disables some of those if they are not generally useful (e.g. `matrix_corporal_enabled: false`).
2019-01-16 16:05:48 +00:00
- (optional) [Amazon S3](https://aws.amazon.com/s3/) storage for Synapse's content repository (`media_store`) files using [Goofys](https://github.com/kahing/goofys)
Add support for storing Matrix Synapse's media_store to Amazon S3
2017-09-07 15:26:41 +00:00
Make roles more independent of one another With this change, the following roles are now only dependent on the minimal `matrix-base` role: - `matrix-corporal` - `matrix-coturn` - `matrix-mailer` - `matrix-mxisd` - `matrix-postgres` - `matrix-riot-web` - `matrix-synapse` The `matrix-nginx-proxy` role still does too much and remains dependent on the others. Wiring up the various (now-independent) roles happens via a glue variables file (`group_vars/matrix-servers`). It's triggered for all hosts in the `matrix-servers` group. According to Ansible's rules of priority, we have the following chain of inclusion/overriding now: - role defaults (mostly empty or good for independent usage) - playbook glue variables (`group_vars/matrix-servers`) - inventory host variables (`inventory/host_vars/matrix.<your-domain>`) All roles default to enabling their main component (e.g. `matrix_mxisd_enabled: true`, `matrix_riot_web_enabled: true`). Reasoning: if a role is included in a playbook (especially separately, in another playbook), it should "work" by default. Our playbook disables some of those if they are not generally useful (e.g. `matrix_corporal_enabled: false`).
2019-01-16 16:05:48 +00:00
- (optional, default) [PostgreSQL](https://www.postgresql.org/) database for Synapse. [Using an external PostgreSQL server](docs/configuring-playbook-external-postgres.md) is also possible.
Initial commit
2017-07-31 20:07:30 +00:00
Make roles more independent of one another With this change, the following roles are now only dependent on the minimal `matrix-base` role: - `matrix-corporal` - `matrix-coturn` - `matrix-mailer` - `matrix-mxisd` - `matrix-postgres` - `matrix-riot-web` - `matrix-synapse` The `matrix-nginx-proxy` role still does too much and remains dependent on the others. Wiring up the various (now-independent) roles happens via a glue variables file (`group_vars/matrix-servers`). It's triggered for all hosts in the `matrix-servers` group. According to Ansible's rules of priority, we have the following chain of inclusion/overriding now: - role defaults (mostly empty or good for independent usage) - playbook glue variables (`group_vars/matrix-servers`) - inventory host variables (`inventory/host_vars/matrix.<your-domain>`) All roles default to enabling their main component (e.g. `matrix_mxisd_enabled: true`, `matrix_riot_web_enabled: true`). Reasoning: if a role is included in a playbook (especially separately, in another playbook), it should "work" by default. Our playbook disables some of those if they are not generally useful (e.g. `matrix_corporal_enabled: false`).
2019-01-16 16:05:48 +00:00
- (optional, default) a [coturn](https://github.com/coturn/coturn) STUN/TURN server for WebRTC audio/video calls
Update README
2018-08-15 06:01:41 +00:00
Riot is now Element Fixes #586 (Github Issue)
2020-07-17 08:31:20 +00:00
- (optional, default) free [Let's Encrypt](https://letsencrypt.org/) SSL certificate, which secures the connection to the Synapse server and the Element web UI
Initial commit
2017-07-31 20:07:30 +00:00
Update README.md to rename Element
2020-07-15 13:44:49 +00:00
- (optional, default) an [Element](https://app.element.io/) ([formerly Riot](https://element.io/previously-riot)) web UI, which is configured to connect to your own Synapse server by default
Initial commit
2017-07-31 20:07:30 +00:00
merge with upstream
2021-05-25 13:08:00 +00:00
- (optional, default) a [ma1sd](https://github.com/ma1uta/ma1sd) Matrix Identity server
Add mxisd Identity Server support
2018-08-15 07:23:22 +00:00
Make (most) containers start as non-root This makes all containers (except mautrix-telegram and mautrix-whatsapp), start as a non-root user. We do this, because we don't trust some of the images. In any case, we'd rather not trust ALL images and avoid giving `root` access at all. We can't be sure they would drop privileges or what they might do before they do it. Because Postfix doesn't support running as non-root, it had to be replaced by an Exim mail server. The matrix-nginx-proxy nginx container image is patched up (by replacing its main configuration) so that it can work as non-root. It seems like there's no other good image that we can use and that is up-to-date (https://hub.docker.com/r/nginxinc/nginx-unprivileged is outdated). Likewise for riot-web (https://hub.docker.com/r/bubuntux/riot-web/), we patch it up ourselves when starting (replacing the main nginx configuration). Ideally, it would be fixed upstream so we can simplify.
2019-01-27 18:25:13 +00:00
- (optional, default) an [Exim](https://www.exim.org/) mail server, through which all Matrix services send outgoing email (can be configured to relay through another SMTP server)
Initial commit
2017-07-31 20:07:30 +00:00
Make it clearer that not all components are necessary
2018-11-26 08:35:08 +00:00
- (optional, default) an [nginx](http://nginx.org/) web server, listening on ports 80 and 443 - standing in front of all the other services. Using your own webserver [is possible](docs/configuring-playbook-own-webserver.md)
Add support for not taking over a server (no matrix-nginx-proxy) and disabling Riot
2017-09-12 09:41:44 +00:00
Replace mxisd with ma1sd in docs, fixing URLs
2020-01-07 18:04:26 +00:00
- (optional, advanced) the [matrix-synapse-rest-auth](https://github.com/ma1uta/matrix-synapse-rest-password-provider) REST authentication password provider module
Add matrix-synapse-rest-auth support
2018-08-17 06:02:12 +00:00
Make it clearer that not all components are necessary
2018-11-26 08:35:08 +00:00
- (optional, advanced) the [matrix-synapse-shared-secret-auth](https://github.com/devture/matrix-synapse-shared-secret-auth) password provider module
Update README
2018-08-20 14:30:05 +00:00
Add LDAP auth password provider documentation and changelog description
2018-11-28 09:21:03 +00:00
- (optional, advanced) the [matrix-synapse-ldap3](https://github.com/matrix-org/matrix-synapse-ldap3) LDAP Auth password provider module
Update README
2019-09-09 05:17:35 +00:00
- (optional, advanced) the [synapse-simple-antispam](https://github.com/t2bot/synapse-simple-antispam) spam checker module
Make it clearer that not all components are necessary
2018-11-26 08:35:08 +00:00
- (optional, advanced) the [Matrix Corporal](https://github.com/devture/matrix-corporal) reconciliator and gateway for a managed Matrix server
Update README
2018-08-26 15:12:24 +00:00
Update README
2018-09-08 07:21:09 +00:00
- (optional) the [mautrix-telegram](https://github.com/tulir/mautrix-telegram) bridge for bridging your Matrix server to [Telegram](https://telegram.org/)
merge with upstream
2021-05-25 13:08:00 +00:00
- (optional) the [mautrix-whatsapp](https://github.com/tulir/mautrix-whatsapp) bridge for bridging your Matrix server to [WhatsApp](https://www.whatsapp.com/)
Update README
2018-10-26 16:48:49 +00:00
Add description of mautrix hangouts bridge in readme
2019-08-20 05:36:16 +00:00
- (optional) the [mautrix-facebook](https://github.com/tulir/mautrix-facebook) bridge for bridging your Matrix server to [Facebook](https://facebook.com/)
- (optional) the [mautrix-hangouts](https://github.com/tulir/mautrix-hangouts) bridge for bridging your Matrix server to [Google Hangouts](https://en.wikipedia.org/wiki/Google_Hangouts)
Add mautrix-facebook doc
2019-05-08 14:33:09 +00:00
update informational files.
2021-02-19 18:37:36 +00:00
- (optional) the [mautrix-instagram](https://github.com/tulir/mautrix-instagram) bridge for bridging your Matrix server to [Instagram](https://instagram.com/)
Announce mautrix-signal bridge
2021-01-03 05:59:49 +00:00
- (optional) the [mautrix-signal](https://github.com/tulir/mautrix-signal) bridge for bridging your Matrix server to [Signal](https://www.signal.org/)
Fix matrix-appservice-irc database specification This fixes an incorrect indentation in the database specification for appservice-irc which caused matrix-appservice-irc to refuse to start with the remarkably unhelpful error message: ``` ERROR:CLI Failed to run bridge. ``` This also updates doc links to the new matrixdotorg repo because the tedomum repo contains out-of-date documentation.
2020-02-08 10:02:03 +00:00
- (optional) the [matrix-appservice-irc](https://github.com/matrix-org/matrix-appservice-irc) bridge for bridging your Matrix server to [IRC](https://wikipedia.org/wiki/Internet_Relay_Chat)
Add support for matrix-appservice-irc
2019-01-31 05:37:23 +00:00
Add matrix-appservice-discord bridge Bridge is setup to work on the matrix side with this, but the discord invite link is not automatically generated.
2019-03-03 17:22:52 +00:00
- (optional) the [matrix-appservice-discord](https://github.com/Half-Shot/matrix-appservice-discord) bridge for bridging your Matrix server to [Discord](https://discordapp.com/)
Update changelog
2019-08-21 04:48:42 +00:00
- (optional) the [matrix-appservice-slack](https://github.com/matrix-org/matrix-appservice-slack) bridge for bridging your Matrix server to [Slack](https://slack.com/)
Add matrix-appservice-webhooks to configurable services in README.md
2020-01-10 14:04:23 +00:00
- (optional) the [matrix-appservice-webhooks](https://github.com/turt2live/matrix-appservice-webhooks) bridge for slack compatible webhooks ([ConcourseCI](https://concourse-ci.org/), [Slack](https://slack.com/) etc. pp.)
Add mx-puppet-skype and mx-puppet-slack to README I also moved matrix-sms-bridge up to match the order from container-images.md
2021-01-29 23:31:27 +00:00
- (optional) the [matrix-sms-bridge](https://github.com/benkuly/matrix-sms-bridge) for bridging your Matrix server to SMS - see [docs/configuring-playbook-bridge-matrix-bridge-sms.md](docs/configuring-playbook-bridge-matrix-bridge-sms.md) for setup documentation
merge with upstream
2021-05-25 13:08:00 +00:00
- (optional) the [Heisenbridge](https://github.com/hifi/heisenbridge) for bridging your Matrix server to IRC bouncer-style - see [docs/configuring-playbook-bridge-heisenbridge.md](docs/configuring-playbook-bridge-heisenbridge.md) for setup documentation
Add mx-puppet-skype and mx-puppet-slack to README I also moved matrix-sms-bridge up to match the order from container-images.md
2021-01-29 23:31:27 +00:00
- (optional) the [mx-puppet-skype](https://hub.docker.com/r/sorunome/mx-puppet-skype) for bridging your Matrix server to [Skype](https://www.skype.com) - see [docs/configuring-playbook-bridge-mx-puppet-skype.md](docs/configuring-playbook-bridge-mx-puppet-skype.md) for setup documentation
fix typo from skype to slack
2021-02-08 17:22:59 +00:00
- (optional) the [mx-puppet-slack](https://hub.docker.com/r/sorunome/mx-puppet-slack) for bridging your Matrix server to [Slack](https://slack.com) - see [docs/configuring-playbook-bridge-mx-puppet-slack.md](docs/configuring-playbook-bridge-mx-puppet-slack.md) for setup documentation
Add mx-puppet-skype and mx-puppet-slack to README I also moved matrix-sms-bridge up to match the order from container-images.md
2021-01-29 23:31:27 +00:00
mx-puppet-instagram: add documentation on how to setup & use the bridge
2020-06-28 08:46:39 +00:00
- (optional) the [mx-puppet-instagram](https://github.com/Sorunome/mx-puppet-instagram) bridge for Instagram-DMs ([Instagram](https://www.instagram.com/)) - see [docs/configuring-playbook-bridge-mx-puppet-instagram.md](docs/configuring-playbook-bridge-mx-puppet-instagram.md) for setup documentation
Mention Prometheus/Grafana on the README
2021-02-12 14:32:49 +00:00
- (optional) the [mx-puppet-twitter](https://github.com/Sorunome/mx-puppet-twitter) bridge for Twitter-DMs ([Twitter](https://twitter.com/)) - see [docs/configuring-playbook-bridge-mx-puppet-twitter.md](docs/configuring-playbook-bridge-mx-puppet-twitter.md) for setup documentation
Announce mx-puppet-discord bridging support Related to #540 (Github Pull Request).
2020-07-01 16:01:14 +00:00
Mention Prometheus/Grafana on the README
2021-02-12 14:32:49 +00:00
- (optional) the [mx-puppet-discord](https://github.com/matrix-discord/mx-puppet-discord) bridge for [Discord](https://discordapp.com/) - see [docs/configuring-playbook-bridge-mx-puppet-discord.md](docs/configuring-playbook-bridge-mx-puppet-discord.md) for setup documentation
Announce mx-puppet-instagram and mx-puppet-twitter support Related to #551 and #555 (Github Pull Requests).
2020-06-30 14:51:56 +00:00
Add docs
2021-02-13 15:55:54 +00:00
- (optional) the [mx-puppet-groupme](https://gitlab.com/robintown/mx-puppet-groupme) bridge for [GroupMe](https://groupme.com/) - see [docs/configuring-playbook-bridge-mx-puppet-groupme.md](docs/configuring-playbook-bridge-mx-puppet-groupme.md) for setup documentation
Mention Prometheus/Grafana on the README
2021-02-12 14:32:49 +00:00
- (optional) the [mx-puppet-steam](https://github.com/icewind1991/mx-puppet-steam) bridge for [Steam](https://steamapp.com/) - see [docs/configuring-playbook-bridge-mx-puppet-steam.md](docs/configuring-playbook-bridge-mx-puppet-steam.md) for setup documentation
Announce mx-puppet-steam bridging support Related to #557 (Github Pull Request).
2020-07-03 09:10:57 +00:00
Add matrix-registration support
2020-09-01 10:46:05 +00:00
- (optional) [Email2Matrix](https://github.com/devture/email2matrix) for relaying email messages to Matrix rooms - see [docs/configuring-playbook-email2matrix.md](docs/configuring-playbook-email2matrix.md) for setup documentation
Update README
2019-08-05 10:12:42 +00:00
Add matrix-registration support
2020-09-01 10:46:05 +00:00
- (optional) [Dimension](https://github.com/turt2live/matrix-dimension), an open source integrations manager for matrix clients - see [docs/configuring-playbook-dimension.md](docs/configuring-playbook-dimension.md) for setup documentation
Provide Dimension documentation
2019-03-10 08:12:31 +00:00
Etherpad documentation
2021-01-20 14:52:26 +00:00
- (optional) [Etherpad](https://etherpad.org), an open source collaborative text editor - see [docs/configuring-playbook-etherpad.md](docs/configuring-playbook-etherpad.md) for setup documentation
Add matrix-registration support
2020-09-01 10:46:05 +00:00
- (optional) [Jitsi](https://jitsi.org/), an open source video-conferencing platform - see [docs/configuring-playbook-jitsi.md](docs/configuring-playbook-jitsi.md) for setup documentation
Update documentation and changelog
2020-03-24 13:30:14 +00:00
Add matrix-registration support
2020-09-01 10:46:05 +00:00
- (optional) [matrix-reminder-bot](https://github.com/anoadragon453/matrix-reminder-bot) for scheduling one-off & recurring reminders and alarms - see [docs/configuring-playbook-bot-matrix-reminder-bot.md](docs/configuring-playbook-bot-matrix-reminder-bot.md) for setup documentation
Add support for matrix-reminder-bot
2020-07-20 11:13:08 +00:00
Added a link to the doc in the README
2021-03-12 15:57:49 +00:00
- (optional) [Go-NEB](https://github.com/matrix-org/go-neb) multi functional bot written in Go - see [docs/configuring-playbook-bot-go-neb.md](docs/configuring-playbook-bot-go-neb.md) for setup documentation
Add mjolnir
2021-03-24 03:46:08 +00:00
- (optional) [Mjolnir](https://github.com/matrix-org/mjolnir), a moderation tool for Matrix - see [docs/configuring-playbook-bot-mjolnir.md](docs/configuring-playbook-bot-mjolnir.md) for setup documentation
Add matrix-registration support
2020-09-01 10:46:05 +00:00
- (optional) [synapse-admin](https://github.com/Awesome-Technologies/synapse-admin), a web UI tool for administrating users and rooms on your Matrix server - see [docs/configuring-playbook-synapse-admin.md](docs/configuring-playbook-synapse-admin.md) for setup documentation
- (optional) [matrix-registration](https://github.com/ZerataX/matrix-registration), a simple python application to have a token based matrix registration - see [docs/configuring-playbook-matrix-registration.md](docs/configuring-playbook-matrix-registration.md) for setup documentation
Add synapse-admin support Fixes #562 (Github Issue)
2020-07-22 05:10:26 +00:00
Mention Prometheus/Grafana on the README
2021-02-12 14:32:49 +00:00
- (optional) the [Prometheus](https://prometheus.io) time-series database server, the Prometheus [node-exporter](https://prometheus.io/docs/guides/node-exporter/) host metrics exporter, and the [Grafana](https://grafana.com/) web UI - see [Enabling metrics and graphs (Prometheus, Grafana) for your Matrix server](docs/configuring-playbook-prometheus-grafana.md) for setup documentation
Add Sygnal support Fixes https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/683
2021-03-20 11:31:34 +00:00
- (optional) the [Sygnal](https://github.com/matrix-org/sygnal) push gateway - see [Setting up the Sygnal push gateway](docs/configuring-playbook-sygnal.md) for setup documentation
merge with upstream
2021-05-25 13:08:00 +00:00
- (optional) the [Hydrogen](https://github.com/vector-im/hydrogen-web) web client - see [docs/configuring-playbook-client-hydrogen.md](docs/configuring-playbook-client-hydrogen.md) for setup documentation
Basically, this playbook aims to get you up-and-running with all the necessities around Matrix, without you having to do anything else.
Initial commit
2017-07-31 20:07:30 +00:00
Make it clearer that not all components are necessary
2018-11-26 08:35:08 +00:00
**Note**: the list above is exhaustive. It includes optional or even some advanced components that you will most likely not need.
Sticking with the defaults (which install a subset of the above components) is the best choice, especially for a new installation.
You can always re-run the playbook later to add or remove components.
Initial commit
2017-07-31 20:07:30 +00:00
Split README into a bunch of files in docs/
2018-08-08 07:07:02 +00:00
## Installation
Initial commit
2017-07-31 20:07:30 +00:00
Split README into a bunch of files in docs/
2018-08-08 07:07:02 +00:00
To configure and install Matrix on your own server, follow the [README in the docs/ directory](docs/README.md).
Initial commit
2017-07-31 20:07:30 +00:00
Indicate that some distributions require a manual python install
2018-06-21 06:42:27 +00:00
Split README into a bunch of files in docs/
2018-08-08 07:07:02 +00:00
## Changes
Initial commit
2017-07-31 20:07:30 +00:00
Split README into a bunch of files in docs/
2018-08-08 07:07:02 +00:00
This playbook evolves over time, sometimes with backward-incompatible changes.
Initial commit
2017-07-31 20:07:30 +00:00
Split README into a bunch of files in docs/
2018-08-08 07:07:02 +00:00
When updating the playbook, refer to [the changelog](CHANGELOG.md) to catch up with what's new.
Add support for not taking over a server (no matrix-nginx-proxy) and disabling Riot
2017-09-12 09:41:44 +00:00
Add support information
2018-05-29 06:58:36 +00:00
## Support
Add information about the IRC support channel
2018-11-23 11:23:01 +00:00
- Matrix room: [#matrix-docker-ansible-deploy:devture.com](https://matrix.to/#/#matrix-docker-ansible-deploy:devture.com)
Add support information
2018-05-29 06:58:36 +00:00
merge upstream
2021-06-01 08:00:13 +00:00
- IRC channel: `#matrix-docker-ansible-deploy` on the [Libera Chat](https://libera.chat/) IRC network (irc.libera.chat:6697)
Add information about the IRC support channel
2018-11-23 11:23:01 +00:00
merge with upstream
2021-05-25 13:08:00 +00:00
- GitHub issues: [spantaleev/matrix-docker-ansible-deploy/issues](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues)
## Services by the community
- [etke.cc](https://etke.cc) - matrix-docker-ansible-deploy and system stuff "as a service". That service will create your matrix homeserver on your domain and server (doesn't matter if it's cloud provider or on an old laptop in the corner of your room), (optional) maintains it (server's system updates, cleanup, security adjustments, tuning, etc.; matrix homeserver updates & maintenance) and (optional) provide full-featured email service for your domain
- [GoMatrixHosting](https://gomatrixhosting.com) - matrix-docker-ansible-deploy "as a service" with [Ansible AWX](https://github.com/ansible/awx). Members can be assigned a server from DigitalOcean, or they can connect their on-premises server. This AWX system can manage the updates, configuration, import and export, backups, and monitoring on its own. For more information [see our GitLab group](https://gitlab.com/GoMatrixHosting) or come [visit us on Matrix](https://matrix.to/#/#general:gomatrixhosting.com).
Reference in a new issue Copy permalink