mirror of
https://github.com/spantaleev/matrix-docker-ansible-deploy.git
synced 2024-12-12 08:43:55 +02:00
Slavi Pantaleev
GitHub
commit
8c4711ffa9
42
CHANGELOG.md
42
CHANGELOG.md
@ -163,7 +163,6 @@ It's designed as a more private and [✨ featureful](https://github.com/etkecc/b
|
||||
|
||||
To get started, see the [Setting up baibot](./docs/configuring-playbook-bot-baibot.md) documentation page.
|
||||
|
||||
|
||||
## Switching synapse-admin to etke.cc's fork
|
||||
|
||||
The playbook now installs [etke.cc](https://etke.cc/)'s [fork](https://github.com/etkecc/synapse-admin) of [synapse-admin](https://github.com/Awesome-Technologies/synapse-admin) (originally developed by [Awesome-Technologies](https://github.com/Awesome-Technologies)). This fork is a drop-in replacement for the original software.
|
||||
@ -252,7 +251,6 @@ For those wishing to more easily integrate [Prometheus](https://prometheus.io/)'
|
||||
|
||||
See [Setting up Prometheus Alertmanager integration via matrix-alertmanager-receiver](./docs/configuring-playbook-alertmanager-receiver.md) for more details.
|
||||
|
||||
|
||||
## Traefik v3 and HTTP/3 are here now
|
||||
|
||||
**TLDR**: Traefik was migrated from v2 to v3. Minor changes were done to the playbook. Mostly everything else worked out of the box. Most people will not have to do any tweaks to their configuration. In addition, [HTTP/3](https://en.wikipedia.org/wiki/HTTP/3) support is now auto-enabled for the `web-secure` (port 443) and `matrix-federation` (port `8448`) entrypoints. If you have a firewall in front of your server and you wish to benefit from `HTTP3`, you will need to open the `443` and `8448` UDP ports in it.
|
||||
@ -273,7 +271,6 @@ If you've tweaked any of this playbook's `_path_prefix` variables and made them
|
||||
|
||||
If you're not using [matrix-media-repo](./docs/configuring-playbook-matrix-media-repo.md) (the only role we had to tweak to adapt it to Traefik v3), you **may potentially downgrade to Traefik v2** (if necessary) by adding `traefik_verison: v2.11.4` to your configuration. People using `matrix-media-repo` cannot downgrade this way, because `matrix-media-repo` has been adjusted to use `PathRegexp` - a [routing matcher](https://doc.traefik.io/traefik/v2.11/routing/routers/#rule) that Traefik v2 does not understand.
|
||||
|
||||
|
||||
### HTTP/3 is enabled by default
|
||||
|
||||
In Traefik v3, [HTTP/3](https://en.wikipedia.org/wiki/HTTP/3) support is no longer considered experimental now.
|
||||
@ -347,7 +344,6 @@ When generating new webhooks, you should start seeing the new URLs being used.
|
||||
However, **we recommend that you update all your old webhook URLs** (configured in other systems) to include the new `/webhook` path component, so that future Hookshot changes (whenever they come) will not break your webhooks. You don't need to do anything on the Hookshot side - you merely need to reconfigure the remote systems that use your webhook URLs.
|
||||
|
||||
|
||||
|
||||
# 2024-06-22
|
||||
|
||||
## The maubot user is now managed by the playbook
|
||||
@ -394,7 +390,6 @@ keydb_enabled: false
|
||||
```
|
||||
|
||||
|
||||
|
||||
# 2024-03-24
|
||||
|
||||
## Initial work on IPv6 support
|
||||
@ -564,7 +559,6 @@ Due to complexity and the playbook's flexibility (trying to accommodate a mix of
|
||||
|
||||
After **a ton of work** in the last weeks (200+ commits, which changed 467 files - 8684 insertions and 8913 deletions), **we're finally saying goodbye** to `matrix-nginx-proxy`.
|
||||
|
||||
|
||||
### Going Traefik-native and cutting out all middlemen
|
||||
|
||||
In our new setup, you'll see the bare minimum number of reverse-proxies.
|
||||
@ -574,7 +568,6 @@ In most cases, there's only Traefik and all services being registered directly w
|
||||
This reduces "network" hops (improving performance) and also decreases the number of components (containers).
|
||||
Each Ansible role in our setup is now independent and doesn't need to interact with other roles during runtime.
|
||||
|
||||
|
||||
### Traefik now has an extra job
|
||||
|
||||
Previously, **Traefik had a single purpose** - being the main reverse-proxy. It was either front-most (terminating SSL, etc.) or you were [fronting Traefik with your own other reverse-proxy](./docs/configuring-playbook-own-webserver.md#fronting-the-integrated-reverse-proxy-webserver-with-another-reverse-proxy). In any case - it had this central (yet decentralized) job.
|
||||
@ -600,21 +593,18 @@ People running the default Traefik setup do not need to do anything to make Trae
|
||||
|
||||
You may disable Traefik acting as an intermediary by explicitly setting `matrix_playbook_public_matrix_federation_api_traefik_entrypoint_enabled` to `false`. Services would then be configured to talk to the homeserver directly, giving you a slight performance boost and a "simpler" Traefik setup. However, such a configuration is less tested and will cause troubles, especially if you enable more services (like `matrix-media-repo`, etc.) in the future. As such, it's not recommended.
|
||||
|
||||
|
||||
### People managing their own Traefik instance need to do minor changes
|
||||
|
||||
This section is for people [managing their own Traefik instance on the Matrix server](./docs/configuring-playbook-own-webserver.md#traefik-managed-by-you). Those [using Traefik managed by the playbook](./docs/configuring-playbook-own-webserver.md#traefik-managed-by-the-playbook) don't need to do any changes.
|
||||
|
||||
Because [Traefik has an extra job now](#traefik-now-has-an-extra-job), you need to adapt your configuration to add the additional `matrix-internal-matrix-client-api` entrypoint and potentially configure the `matrix_playbook_reverse_proxy_container_network` variable. See the [Traefik managed by you](./docs/configuring-playbook-own-webserver.md#traefik-managed-by-you) documentation section for more details.
|
||||
|
||||
|
||||
### People fronting Traefik with another reverse proxy need to do minor changes
|
||||
|
||||
We've already previously mentioned that you need to do some minor [configuration changes related to `traefik_additional_entrypoints_auto`](#backward-compatibility-configuration-changes-required-for-people-fronting-the-integrated-reverse-proxy-webserver-with-another-reverse-proxy).
|
||||
|
||||
If you don't do these changes (switching from `traefik_additional_entrypoints_auto` to multiple other variables), your Traefik setup will not automatically receive the new `matrix-internal-matrix-client-api` Traefik entrypoint and Traefik would not be able to perform [its new duty of connecting addons with the homeserver](#traefik-now-has-an-extra-job).
|
||||
|
||||
|
||||
### Supported reverse proxy types are now fewer
|
||||
|
||||
This section is for people using a more custom reverse-proxy setup - those having `matrix_playbook_reverse_proxy_type` set to a value different than the default (`playbook-managed-traefik`).
|
||||
@ -636,7 +626,6 @@ If you were using these values as a way to stay away from Traefik, you now have
|
||||
- (recommended) [Fronting Traefik with another reverse-proxy](./docs/configuring-playbook-own-webserver.md#fronting-the-integrated-reverse-proxy-webserver-with-another-reverse-proxy)
|
||||
- (not recommended) [Using no reverse-proxy on the Matrix side at all](./docs/configuring-playbook-own-webserver.md#using-no-reverse-proxy-on-the-matrix-side-at-all) and reverse-proxying to each and every service manually
|
||||
|
||||
|
||||
### Container networking changes
|
||||
|
||||
Now that `matrix-nginx-proxy` is not in the mix, it became easier to clear out some other long-overdue technical debt.
|
||||
@ -651,7 +640,6 @@ Carrying out these container networking changes necessitated modifying many comp
|
||||
|
||||
We've refrained from creating too many container networks (e.g. one for each component), to avoid exhausting Docker's default network pool and contaminating the container networks list too much.
|
||||
|
||||
|
||||
### Metrics exposure changes
|
||||
|
||||
This section is for people who are exposing monitoring metrics publicly, to be consumed by an external Prometheus server.
|
||||
@ -664,7 +652,6 @@ From now on, there are new variables for doing roughly the same - `matrix_metric
|
||||
|
||||
The playbook will tell you about all variables that you need to migrate during runtime, so rest assured - you shouldn't be able to miss anything!
|
||||
|
||||
|
||||
### Matrix static files
|
||||
|
||||
As mentioned above, static files like `/.well-known/matrix/*` or your base domain's `index.html` file (when [serving the base domain via the Matrix server](./docs/configuring-playbook-base-domain-serving.md) was enabled) were generated by the `matrix-base` or `matrix-nginx-proxy` roles and put into a `/matrix/static-files` directory on the server. Then `matrix-nginx-proxy` was serving all these static files.
|
||||
@ -673,7 +660,6 @@ All of this has been extracted into a new `matrix-static-files` Ansible role tha
|
||||
|
||||
The playbook will migrate and update the `/.well-known/matrix/*` files automatically but not your own files in `nginx-proxy/data/matrix-domain/` you will need to back these up yourself otherwise they will be lost. It will also warn you about usage of old variable names, so you can adapt to the new names.
|
||||
|
||||
|
||||
### A note on performance
|
||||
|
||||
Some of you have been voicing their concerns (for a long time) about Traefik being too slow and nginx being better.
|
||||
@ -688,7 +674,6 @@ Even our previously mentioned benchmarks (yielding ~1300 rps) are synthetic - hi
|
||||
|
||||
If this is still not convincing enough for you and you want the best possible performance, consider [Fronting Traefik with another reverse-proxy](./docs/configuring-playbook-own-webserver.md#fronting-the-integrated-reverse-proxy-webserver-with-another-reverse-proxy) (thus having the slowest part - SSL termination - happen elsewhere) or [Using no reverse-proxy on the Matrix side at all](./docs/configuring-playbook-own-webserver.md#using-no-reverse-proxy-on-the-matrix-side-at-all). The playbook will not get in your way of doing that, but these options may make your life much harder. Performance comes at a cost, after all.
|
||||
|
||||
|
||||
### Migration procedure
|
||||
|
||||
The updated playbook will automatically perform some migration tasks for you:
|
||||
@ -710,7 +695,6 @@ We don't recommend changing these variables and suppressing warnings, unless you
|
||||
**Most people should just upgrade as per-normal**, bearing in mind that a lot has changed and some issues may arise.
|
||||
The playbook would guide you through renamed variables automatically.
|
||||
|
||||
|
||||
### Conclusion
|
||||
|
||||
Thousands of lines of code were changed across hundreds of files.
|
||||
@ -1238,7 +1222,6 @@ Some services (like [Coturn](docs/configuring-playbook-turn.md) and [Postmoogle]
|
||||
|
||||
Our Traefik setup mostly works, but certain esoteric features may not work. If you have a default setup, we expect you to have a good experience.
|
||||
|
||||
|
||||
### Where we're going in the near future?
|
||||
|
||||
The `matrix-nginx-proxy` role is quite messy. It manages both nginx and Certbot and its certificate renewal scripts and timers. It generates configuration even when the role is disabled (weird). Although it doesn't directly reach into variables from other roles, it has explicit awareness of various other services that it reverse-proxies to (`roles/custom/matrix-nginx-proxy/templates/nginx/conf.d/matrix-ntfy.conf.j2`, etc.). We'd like to clean this up. The only way is probably to just get rid of the whole thing at some point.
|
||||
@ -1271,7 +1254,6 @@ Thanks to [Jakob S.](https://github.com/jakicoll) ([zakk gGmbH](https://github.c
|
||||
|
||||
Additional details are available in the [Authenticate using Matrix OpenID (Auth-Type 'matrix')](docs/configuring-playbook-jitsi.md#authenticate-using-matrix-openid-auth-type-matrix).
|
||||
|
||||
|
||||
## Draupnir moderation tool (bot) support
|
||||
|
||||
Thanks to [FSG-Cat](https://github.com/FSG-Cat), the playbook can now install and configure the [Draupnir](https://github.com/the-draupnir-project/Draupnir) moderation tool (bot). Draupnir is a fork of [Mjolnir](docs/configuring-playbook-bot-mjolnir.md) (which the playbook has supported for a long time) maintained by Mjolnir's former lead developer.
|
||||
@ -1311,7 +1293,6 @@ This, however, means that **you will need to ensure these ports are open** in yo
|
||||
|
||||
Thanks to us [tightening Coturn security](#backward-compatibility-tightening-coturn-security-can-lead-to-connectivity-issues), running Coturn with host-networking should be safe and not expose neither other services running on the host, nor other services running on the local network.
|
||||
|
||||
|
||||
## (Backward Compatibility) Tightening Coturn security can lead to connectivity issues
|
||||
|
||||
**TLDR**: users who run and access their Matrix server on a private network (likely a small minority of users) may experience connectivity issues with our new default Coturn blocklists. They may need to override `matrix_coturn_denied_peer_ips` and remove some IP ranges from it.
|
||||
@ -1559,7 +1540,6 @@ This is not just for initial installations. Users with existing files (stored in
|
||||
|
||||
To get started, see our [Storing Synapse media files on Amazon S3 with synapse-s3-storage-provider](docs/configuring-playbook-synapse-s3-storage-provider.md) documentation.
|
||||
|
||||
|
||||
## Synapse container image customization support
|
||||
|
||||
We now support customizing the Synapse container image by adding additional build steps to its [`Dockerfile`](https://docs.docker.com/engine/reference/builder/).
|
||||
@ -1773,7 +1753,6 @@ If you still need bridging to [Skype](https://www.skype.com/), consider switchin
|
||||
|
||||
If you think this is a mistake and `mx-puppet-skype` works for you (or you get it to work somehow), let us know and we may reconsider this removal.
|
||||
|
||||
|
||||
## signald (0.19.0+) upgrade requires data migration
|
||||
|
||||
In [Pull Request #1921](https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/1921) we upgraded [signald](https://signald.org/) (used by the mautrix-signal bridge) from `v0.18.5` to `v0.20.0`.
|
||||
@ -1905,7 +1884,6 @@ Thanks to [Aine](https://gitlab.com/etke.cc) of [etke.cc](https://etke.cc/), the
|
||||
|
||||
See our [Setting up BorgBackup](docs/configuring-playbook-backup-borg.md) documentation to get started.
|
||||
|
||||
|
||||
## (Compatibility Break) Upgrading to Synapse v1.57 on setups using workers may require manual action
|
||||
|
||||
If you're running a worker setup for Synapse (`matrix_synapse_workers_enabled: true`), the [Synapse v1.57 upgrade notes](https://github.com/element-hq/synapse/blob/v1.57.0rc1/docs/upgrade.md#changes-to-database-schema-for-application-services) say that you may need to take special care when upgrading:
|
||||
@ -2021,7 +1999,6 @@ matrix_homeserver_implementation: dendrite
|
||||
|
||||
We're excited to gain support for other homeserver implementations, like [Conduit](https://conduit.rs/), etc!
|
||||
|
||||
|
||||
## Honoroit bot support
|
||||
|
||||
Thanks to [Aine](https://gitlab.com/etke.cc) of [etke.cc](https://etke.cc/), the playbook can now help you set up [Honoroit](https://github.com/etkecc/honoroit) - a helpdesk bot.
|
||||
@ -2144,7 +2121,6 @@ Thanks to [foxcris](https://github.com/foxcris), the playbook can now make autom
|
||||
Additional details are available in [Setting up postgres backup](docs/configuring-playbook-postgres-backup.md).
|
||||
|
||||
|
||||
|
||||
# 2021-04-03
|
||||
|
||||
## Mjolnir moderation tool (bot) support
|
||||
@ -2471,7 +2447,6 @@ We've removed support for the unmaintained [synapse-janitor](https://github.com/
|
||||
|
||||
If you need to clean up or compact your database, consider using the Synapse Admin APIs directly. See our [Synapse maintenance](docs/maintenance-synapse.md) and [Postgres maintenance](docs/maintenance-postgres.md) documentation pages for more details.
|
||||
|
||||
|
||||
## Docker 20.10 is here
|
||||
|
||||
(No need to do anything special in relation to this. Just something to keep in mind)
|
||||
@ -2999,7 +2974,6 @@ This greatly reduces the number of log messages that are being logged, leading t
|
||||
If you'd like to track down an issue, you [can always increase the logging level as described here](./docs/maintenance-and-troubleshooting.md#increasing-synapse-logging).
|
||||
|
||||
|
||||
|
||||
# 2019-07-08
|
||||
|
||||
## Synapse Maintenance docs and synapse-janitor support are available
|
||||
@ -3010,7 +2984,6 @@ There's a new documentation page about [Synapse maintenance](./docs/maintenance-
|
||||
|
||||
Among other things, if your Postgres database has grown significantly over time, you may wish to [ask the playbook to purge unused data with synapse-janitor](./docs/maintenance-synapse.md#purging-unused-data-with-synapse-janitor) for you.
|
||||
|
||||
|
||||
## (BC Break) Rename run control variables
|
||||
|
||||
Some internal playbook control variables have been renamed.
|
||||
@ -3222,7 +3195,6 @@ If you're using your own Synapse instance (especially one not running in a conta
|
||||
|
||||
Having Synapse not be a required component potentially opens the door for installing alternative Matrix homeservers.
|
||||
|
||||
|
||||
## Bridges are now separate from the Synapse role
|
||||
|
||||
Bridges are no longer part of the `matrix-synapse` role.
|
||||
@ -3230,7 +3202,6 @@ Each bridge now lives in its own separate role (`roles/custom/matrix-bridge-*`).
|
||||
|
||||
These bridge roles are independent of the `matrix-synapse` role, so it should be possible to use them with a Synapse instance installed another way (not through the playbook).
|
||||
|
||||
|
||||
## Renaming inconsistently-named Synapse variables
|
||||
|
||||
For better consistency, the following variables have been renamed:
|
||||
@ -3311,7 +3282,6 @@ If you don't have a dedicated server for your base domain and want to set up [Se
|
||||
It's now possible for the playbook to obtain an SSL certificate and serve the necessary files for Matrix Server Delegation on your base domain.
|
||||
Take a look at the new [Serving the base domain](docs/configuring-playbook-base-domain-serving.md) documentation page.
|
||||
|
||||
|
||||
## (BC break) matrix-nginx-proxy data variable renamed
|
||||
|
||||
`matrix_nginx_proxy_data_path` was renamed to `matrix_nginx_proxy_base_path`.
|
||||
@ -3435,7 +3405,6 @@ Containers are given write access only to the directories they need to write to.
|
||||
A minor breaking change is the `matrix_nginx_proxy_proxy_matrix_client_api_client_max_body_size` variable having being renamed to `matrix_nginx_proxy_proxy_matrix_client_api_client_max_body_size_mb` (note the `_mb` suffix). The new variable expects a number value (e.g. `25M` -> `25`).
|
||||
If you weren't customizing this variable, this wouldn't affect you.
|
||||
|
||||
|
||||
## matrix-mailer is now based on Exim, not Postfix
|
||||
|
||||
While we would have preferred to stay with [Postfix](http://www.postfix.org/), we found out that it cannot run as a non-root user.
|
||||
@ -3555,7 +3524,6 @@ For people who use Let's Encrypt (mostly everyone, since it's the default), you'
|
||||
- before: `host_specific_matrix_ssl_support_email`
|
||||
- after: `host_specific_matrix_ssl_lets_encrypt_support_email`
|
||||
|
||||
|
||||
## (BC Break) mxisd upgrade with multiple base DN support
|
||||
|
||||
mxisd has bee upgraded to [version 1.2.2](https://github.com/kamax-matrix/mxisd/releases/tag/v1.2.2), which supports [multiple base DNs](https://github.com/kamax-matrix/mxisd/blob/v1.2.2/docs/stores/ldap.md#base).
|
||||
@ -3676,7 +3644,6 @@ The playbook now installs [Postgres 11](https://www.postgresql.org/about/news/18
|
||||
|
||||
If you have have an existing setup, it's likely running on an older Postgres version (9.x or 10.x). You can easily upgrade by following the [upgrading PostgreSQL guide](docs/maintenance-postgres.md#upgrading-postgresql).
|
||||
|
||||
|
||||
## (BC Break) Renaming playbook variables
|
||||
|
||||
Due to the large amount of features added to this playbook lately, to keep things manageable we've had to reorganize its configuration variables a bit.
|
||||
@ -3766,7 +3733,6 @@ The playbook now helps you set up [service discovery](https://matrix.org/docs/sp
|
||||
|
||||
Additional details are available in [Configuring service discovery via .well-known](docs/configuring-well-known.md).
|
||||
|
||||
|
||||
## (BC Break) Renaming playbook variables
|
||||
|
||||
The following playbook variables were renamed:
|
||||
@ -3783,19 +3749,16 @@ The playbook now supports bridging with [Telegram](https://telegram.org/) by ins
|
||||
|
||||
Additional details are available in [Setting up Mautrix Telegram bridging](docs/configuring-playbook-bridge-mautrix-telegram.md).
|
||||
|
||||
|
||||
## Events cache size increase and configurability for Matrix Synapse
|
||||
|
||||
The playbook now lets you configure Matrix Synapse's `event_cache_size` configuration via the `matrix_synapse_event_cache_size` playbook variable.
|
||||
|
||||
Previously, this value was hardcoded to `"10K"`. From now on, a more reasonable default of `"100K"` is used.
|
||||
|
||||
|
||||
## Password-peppering support for Matrix Synapse
|
||||
|
||||
The playbook now supports enabling password-peppering for increased security in Matrix Synapse via the `matrix_synapse_password_config_pepper` playbook variable. Using a password pepper is disabled by default (just like it used to be before this playbook variable got introduced) and is not to be enabled/disabled after initial setup, as that would invalidate all existing passwords.
|
||||
|
||||
|
||||
## Statistics-reporting support for Matrix Synapse
|
||||
|
||||
There's now a new `matrix_synapse_report_stats` playbook variable, which controls the `report_stats` configuration option for Matrix Synapse. It defaults to `false`, so no change is required to retain your privacy.
|
||||
@ -3856,7 +3819,6 @@ The playbook can now install and configure [matrix-synapse-rest-auth](https://gi
|
||||
|
||||
Additional details are available in [Setting up the REST authentication password provider module](docs/configuring-playbook-rest-auth.md).
|
||||
|
||||
|
||||
## Compression improvements
|
||||
|
||||
Shifted Matrix Synapse compression from happening in the Matrix Synapse,
|
||||
@ -3865,7 +3827,6 @@ to happening in the nginx proxy that's in front of it.
|
||||
Additionally, `riot-web` also gets compressed now (in the nginx proxy),
|
||||
which drops the initial page load's size from 5.31MB to 1.86MB.
|
||||
|
||||
|
||||
## Disabling some unnecessary Synapse services
|
||||
|
||||
The following services are not necessary, so they have been disabled:
|
||||
@ -3896,7 +3857,6 @@ With this, Matrix Synapse is able to send email notifications for missed message
|
||||
|
||||
# 2018-08-08
|
||||
|
||||
|
||||
## (BC Break) Renaming playbook variables
|
||||
|
||||
The following playbook variables were renamed:
|
||||
@ -3912,13 +3872,11 @@ The following playbook variables were renamed:
|
||||
|
||||
If you're overriding any of them in your `vars.yml` file, you'd need to change to the new names.
|
||||
|
||||
|
||||
## Renaming Ansible playbook tag
|
||||
|
||||
The command for executing the whole playbook has changed.
|
||||
The `setup-main` tag got renamed to `setup-all`.
|
||||
|
||||
|
||||
## Docker container linking
|
||||
|
||||
Changed the way the Docker containers are linked together. The ones that need to communicate with others operate in a `matrix` network now and not in the default bridge network.
|
||||
|
||||
@ -63,8 +63,6 @@ Web clients for Matrix that you can host on your own domains.
|
||||
| [Cinny](https://github.com/ajbura/cinny) | ❌ | Simple, elegant and secure web client | [Link](docs/configuring-playbook-client-cinny.md) |
|
||||
| [SchildiChat Web](https://schildi.chat/) | ❌ | Based on Element Web, with a more traditional instant messaging experience | [Link](docs/configuring-playbook-client-schildichat-web.md) |
|
||||
|
||||
|
||||
|
||||
### Server Components
|
||||
|
||||
Services that run on the server to make the various parts of your installation work.
|
||||
@ -79,7 +77,6 @@ Services that run on the server to make the various parts of your installation w
|
||||
| [ma1sd](https://github.com/ma1uta/ma1sd) | ❌ | Matrix Identity Server | [Link](docs/configuring-playbook-ma1sd.md)
|
||||
| [ddclient](https://github.com/linuxserver/docker-ddclient) | ❌ | Dynamic DNS | [Link](docs/configuring-playbook-dynamic-dns.md) |
|
||||
|
||||
|
||||
### Authentication
|
||||
|
||||
Extend and modify how users are authenticated on your homeserver.
|
||||
@ -94,7 +91,6 @@ Extend and modify how users are authenticated on your homeserver.
|
||||
| [Matrix User Verification Service](https://github.com/matrix-org/matrix-user-verification-service) (UVS) | ❌ | Service to verify details of a user based on an Open ID token | [Link](docs/configuring-playbook-user-verification-service.md) |
|
||||
| [synapse-simple-antispam](https://github.com/t2bot/synapse-simple-antispam) (advanced) | ❌ | A spam checker module | [Link](docs/configuring-playbook-synapse-simple-antispam.md) |
|
||||
|
||||
|
||||
### File Storage
|
||||
|
||||
Use alternative file storage to the default `media_store` folder.
|
||||
@ -140,7 +136,6 @@ Bridges can be used to connect your Matrix installation with third-party communi
|
||||
| [Email2Matrix](https://github.com/devture/email2matrix) | ❌ | Bridge for relaying emails to Matrix rooms | [Link](docs/configuring-playbook-email2matrix.md) |
|
||||
| [Postmoogle](https://github.com/etkecc/postmoogle) | ❌ | Email to Matrix bridge | [Link](docs/configuring-playbook-bridge-postmoogle.md) |
|
||||
|
||||
|
||||
### Bots
|
||||
|
||||
Bots provide various additional functionality to your installation.
|
||||
@ -187,14 +182,12 @@ Various services that don't fit any other categories.
|
||||
| [Sygnal](https://github.com/matrix-org/sygnal) | ❌ | Push gateway | [Link](docs/configuring-playbook-sygnal.md) |
|
||||
| [ntfy](https://ntfy.sh) | ❌ | Push notifications server | [Link](docs/configuring-playbook-ntfy.md) |
|
||||
|
||||
|
||||
## 🆕 Changes
|
||||
|
||||
This playbook evolves over time, sometimes with backward-incompatible changes.
|
||||
|
||||
When updating the playbook, refer to [the changelog](CHANGELOG.md) to catch up with what's new.
|
||||
|
||||
|
||||
## 🆘 Support
|
||||
|
||||
- Matrix room: [#matrix-docker-ansible-deploy:devture.com](https://matrix.to/#/#matrix-docker-ansible-deploy:devture.com)
|
||||
@ -203,7 +196,6 @@ When updating the playbook, refer to [the changelog](CHANGELOG.md) to catch up w
|
||||
|
||||
- GitHub issues: [spantaleev/matrix-docker-ansible-deploy/issues](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues)
|
||||
|
||||
|
||||
## 🤝 Related
|
||||
|
||||
You may also be interested in [mash-playbook](https://github.com/mother-of-all-self-hosting/mash-playbook) - another Ansible playbook for self-hosting non-Matrix services (see its [List of supported services](https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/docs/supported-services.md)).
|
||||
|
||||
@ -10,7 +10,6 @@ The playbook automatically determines the target server's architecture (the `mat
|
||||
|
||||
Some tools and container images can be built on the host or other measures can be used to install on that architecture.
|
||||
|
||||
|
||||
## Implementation details
|
||||
|
||||
For `amd64`, prebuilt container images (see the [container images we use](container-images.md)) are used for all components (except [Hydrogen](configuring-playbook-client-hydrogen.md), which goes through self-building).
|
||||
|
||||
@ -5,7 +5,6 @@ This playbook is meant to be run using [Ansible](https://www.ansible.com/).
|
||||
|
||||
Ansible typically runs on your local computer and carries out tasks on a remote server. If your local computer cannot run Ansible, you can also run Ansible on some server somewhere (including the server you wish to install to).
|
||||
|
||||
|
||||
## Supported Ansible versions
|
||||
|
||||
To manually check which version of Ansible you're on, run: `ansible --version`.
|
||||
@ -16,7 +15,6 @@ We're not sure what's the minimum version of Ansible that can run this playbook
|
||||
|
||||
If your distro ships with an Ansible version older than this, you may run into issues. Consider [Upgrading Ansible](#upgrading-ansible) or [using Ansible via Docker](#using-ansible-via-docker).
|
||||
|
||||
|
||||
## Upgrading Ansible
|
||||
|
||||
Depending on your distribution, you may be able to upgrade Ansible in a few different ways:
|
||||
@ -27,10 +25,8 @@ Depending on your distribution, you may be able to upgrade Ansible in a few diff
|
||||
|
||||
If using the `pip` method, do note that the `ansible-playbook` binary may not be on the `$PATH` (https://linuxconfig.org/linux-path-environment-variable), but in some more special location like `/usr/local/bin/ansible-playbook`. You may need to invoke it using the full path.
|
||||
|
||||
|
||||
**Note**: Both of the above methods are a bad way to run system software such as Ansible. If you find yourself needing to resort to such hacks, please consider reporting a bug to your distribution and/or switching to a sane distribution, which provides up-to-date software.
|
||||
|
||||
|
||||
## Using Ansible via Docker
|
||||
|
||||
Alternatively, you can run Ansible inside a Docker container (powered by the [devture/ansible](https://hub.docker.com/r/devture/ansible/) Docker image).
|
||||
@ -39,7 +35,6 @@ This ensures that you're using a very recent Ansible version, which is less like
|
||||
|
||||
You can either [run Ansible in a container on the Matrix server itself](#running-ansible-in-a-container-on-the-matrix-server-itself) or [run Ansible in a container on another computer (not the Matrix server)](#running-ansible-in-a-container-on-another-computer-not-the-matrix-server).
|
||||
|
||||
|
||||
### Running Ansible in a container on the Matrix server itself
|
||||
|
||||
To run Ansible in a (Docker) container on the Matrix server itself, you need to have a working Docker installation. Docker is normally installed by the playbook, so this may be a bit of a chicken and egg problem. To solve it:
|
||||
@ -71,7 +66,6 @@ First, consider running `git config --global --add safe.directory /work` to [res
|
||||
|
||||
Finally, you can execute `ansible-playbook ...` (or `ansible-playbook --connection=community.docker.nsenter ...`) commands as per normal now.
|
||||
|
||||
|
||||
### Running Ansible in a container on another computer (not the Matrix server)
|
||||
|
||||
Run this from the playbook's directory:
|
||||
@ -93,17 +87,17 @@ First, consider running `git config --global --add safe.directory /work` to [res
|
||||
|
||||
Finally, you execute `ansible-playbook ...` commands as per normal now.
|
||||
|
||||
|
||||
#### If you don't use SSH keys for authentication
|
||||
|
||||
If you don't use SSH keys for authentication, simply remove that whole line (`-v $HOME/.ssh/id_rsa:/root/.ssh/id_rsa:ro`).
|
||||
|
||||
To authenticate at your server using a password, you need to add a package. So, when you are in the shell of the ansible docker container (the previously used `docker run -it ...` command), run:
|
||||
|
||||
```sh
|
||||
apk add sshpass
|
||||
```
|
||||
Then, to be asked for the password whenever running an `ansible-playbook` command add `--ask-pass` to the arguments of the command.
|
||||
|
||||
Then, to be asked for the password whenever running an `ansible-playbook` command add `--ask-pass` to the arguments of the command.
|
||||
|
||||
#### Resolve directory ownership issues
|
||||
|
||||
|
||||
@ -1,6 +1,7 @@
|
||||
(Adapted from the [upstream project](https://github.com/element-hq/synapse/blob/develop/docs/CAPTCHA_SETUP.md))
|
||||
|
||||
# Overview
|
||||
|
||||
Captcha can be enabled for this home server. This file explains how to do that.
|
||||
|
||||
The captcha mechanism used is Google's [ReCaptcha](https://www.google.com/recaptcha/). This requires API keys from Google. If your homeserver is Dendrite then [hCapcha](https://www.hcaptcha.com) can be used instead.
|
||||
|
||||
@ -73,7 +73,6 @@ Steps 1 and 2 above only need to be done once, while preparing your [configurati
|
||||
|
||||
Steps 3 and 4 need to be done for each new room you'd like the bot to deliver alerts to. Step 5 is optional and provides cleaner `/alert/` URLs.
|
||||
|
||||
|
||||
## Installing
|
||||
|
||||
Now that you've [prepared the bot account and room](#account-and-room-preparation), [configured the playbook](#adjusting-the-playbook-configuration), and potentially [adjusted your DNS records](#adjusting-dns-records), you can run the playbook with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
@ -4,7 +4,6 @@ The playbook can install and configure the [Draupnir](https://github.com/the-dra
|
||||
|
||||
Appservice mode can be used together with the regular [Draupnir bot](configuring-playbook-bot-draupnir.md) or independently. Details about the differences between the 2 modes are described below.
|
||||
|
||||
|
||||
## Draupnir Appservice mode compared to Draupnir bot mode
|
||||
|
||||
The administrative functions for managing the appservice are alpha quality and very limited. However, the experience of using an appservice-provisioned Draupnir is on par with the experience of using Draupnir from bot mode except in the case of avatar customisation as described later on in this document.
|
||||
@ -17,7 +16,6 @@ Normal Draupnir does come with the benefit of access to Synapse Admin features.
|
||||
|
||||
Draupnir for all does not support external tooling like [MRU](https://mru.rory.gay) as it can't access Draupnir's user account.
|
||||
|
||||
|
||||
## Installation
|
||||
|
||||
### 1. Create a main management room.
|
||||
|
||||
@ -33,7 +33,6 @@ Doing this, the playbook will:
|
||||
|
||||
- serve a simple homepage at `https://example.com` with content `Hello from example.com` (configurable via the `matrix_static_files_file_index_html_template` variable). You can also [serve a more complicated static website](#serving-a-static-website-at-the-base-domain).
|
||||
|
||||
|
||||
## Serving a static website at the base domain
|
||||
|
||||
By default, when "serving the base domain" is enabled, the playbook hosts a simple `index.html` webpage at `/matrix/static-files/public/index.html`. The content of this page is taken from the `matrix_static_files_file_index_html_template` variable.
|
||||
@ -56,7 +55,6 @@ With this configuration, Ansible will no longer mess around with the `/matrix/st
|
||||
|
||||
You are then free to upload any static website files to `/matrix/static-files/public` and they will get served at the base domain. You can do so manually or by using the [ansible-role-aux](https://github.com/mother-of-all-self-hosting/ansible-role-aux) Ansible role, which is part of this playbook already.
|
||||
|
||||
|
||||
## Serving a more complicated website at the base domain
|
||||
|
||||
If you'd like to serve an even more complicated (dynamic) website from the Matrix server, relying on the playbook to serve the base domain is not the best choice.
|
||||
|
||||
@ -11,12 +11,10 @@ It supports [OpenAI](https://openai.com/)'s [ChatGPT](https://openai.com/blog/ch
|
||||
|
||||
It's designed as a more private and [✨ featureful](https://github.com/etkecc/baibot/?tab=readme-ov-file#-features) alternative to [matrix-chatgpt-bot](./configuring-playbook-bot-chatgpt.md). See the [baibot](https://github.com/etkecc/baibot) project and its documentation for more information.
|
||||
|
||||
|
||||
## Prerequisites
|
||||
|
||||
API access to one or more LLM [☁️ providers](https://github.com/etkecc/baibot/blob/main/docs/providers.md).
|
||||
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
There are **a lot of configuration options** (some required, some possibly required, some optional), so they're **split into multiple sections below**:
|
||||
@ -30,7 +28,6 @@ There are **a lot of configuration options** (some required, some possibly requi
|
||||
|
||||
Depending on your current `vars.yml` file and desired configuration, **you may require more than just the [base configuration](#base-configuration)**.
|
||||
|
||||
|
||||
### Base configuration
|
||||
|
||||
Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
@ -73,7 +70,6 @@ matrix_bot_baibot_config_persistence_config_encryption_key: 'A_HEX_STRING_OF_64_
|
||||
|
||||
As mentioned above, **this may not be enough**. Continue with the configuration sections below.
|
||||
|
||||
|
||||
### 👮♂️ Administrator configuration
|
||||
|
||||
This is an addition to the [base configuration](#base-configuration).
|
||||
@ -139,7 +135,6 @@ Depending on your propensity for [GitOps](https://en.wikipedia.org/wiki/DevOps#G
|
||||
|
||||
Before proceeding, we recommend reading the upstream documentation on [How to choose a provider](https://github.com/etkecc/baibot/blob/main/docs/providers.md#how-to-choose-a-provider). In short, it's probably best to go with [OpenAI](#openai).
|
||||
|
||||
|
||||
#### Anthropic
|
||||
|
||||
You can statically-define a single [🤖 agent](https://github.com/etkecc/baibot/blob/main/docs/agents.md) instance powered by the [Anthropic provider](https://github.com/etkecc/baibot/blob/main/docs/providers.md#anthropic) with the help of the playbook's preset variables.
|
||||
@ -166,7 +161,6 @@ If you'd like to use more than one model, take a look at the [Configuring additi
|
||||
|
||||
💡 You may also wish to use this new agent for [🤝 Configuring initial default handlers](#-configuring-initial-default-handlers).
|
||||
|
||||
|
||||
#### Groq
|
||||
|
||||
You can statically-define a single [🤖 agent](https://github.com/etkecc/baibot/blob/main/docs/agents.md) instance powered by the [Groq provider](https://github.com/etkecc/baibot/blob/main/docs/providers.md#groq) with the help of the playbook's preset variables.
|
||||
@ -200,7 +194,6 @@ If you'd like to use more than one model, take a look at the [Configuring additi
|
||||
|
||||
💡 You may also wish to use this new agent for [🤝 Configuring initial default handlers](#-configuring-initial-default-handlers).
|
||||
|
||||
|
||||
#### Mistral
|
||||
|
||||
You can statically-define a single [🤖 agent](https://github.com/etkecc/baibot/blob/main/docs/agents.md) instance powered by the [🇫🇷 Mistral provider](https://github.com/etkecc/baibot/blob/main/docs/providers.md#mistral) with the help of the playbook's preset variables.
|
||||
@ -229,7 +222,6 @@ If you'd like to use more than one model, take a look at the [Configuring additi
|
||||
|
||||
💡 You may also wish to use this new agent for [🤝 Configuring initial default handlers](#-configuring-initial-default-handlers).
|
||||
|
||||
|
||||
#### OpenAI
|
||||
|
||||
You can statically-define a single [🤖 agent](https://github.com/etkecc/baibot/blob/main/docs/agents.md) instance powered by the [OpenAI provider](https://github.com/etkecc/baibot/blob/main/docs/providers.md#openai) with the help of the playbook's preset variables.
|
||||
@ -260,7 +252,6 @@ If you'd like to use more than one model, take a look at the [Configuring additi
|
||||
|
||||
💡 You may also wish to use this new agent for [🤝 Configuring initial default handlers](#-configuring-initial-default-handlers).
|
||||
|
||||
|
||||
#### OpenAI Compatible
|
||||
|
||||
You can statically-define a single [🤖 agent](https://github.com/etkecc/baibot/blob/main/docs/agents.md) instance powered by the [OpenAI Compatible provider](https://github.com/etkecc/baibot/blob/main/docs/providers.md#openai-compatible) with the help of the playbook's preset variables.
|
||||
@ -271,7 +262,6 @@ Some of these popular services already have **shortcut** providers (see [support
|
||||
|
||||
As of this moment, the playbook does not include presets for any of these services, so you'll need to [Configuring additional agents (without a preset)](#configuring-additional-agents-without-a-preset).
|
||||
|
||||
|
||||
#### Configuring additional agents (without a preset)
|
||||
|
||||
The Ansible role may be lacking preset variables for some [☁️ provider](https://github.com/etkecc/baibot/blob/main/docs/providers.md), or you may wish to statically-define an agent on the same provider twice (or more) with different configuration.
|
||||
@ -327,7 +317,6 @@ As with any [🤖 agent](https://github.com/etkecc/baibot/blob/main/docs/agents.
|
||||
|
||||
💡 You may also wish to use these new agents for [🤝 Configuring initial default handlers](#-configuring-initial-default-handlers).
|
||||
|
||||
|
||||
### 🤝 Configuring initial default handlers
|
||||
|
||||
This section is only useful if you're [🤖 Configuring agents via Ansible](#-configuring-agents-via-ansible), as it lets you put these agents to use as soon as the bot starts (by adjusting the bot's **initial global configuration**).
|
||||
@ -373,7 +362,6 @@ matrix_bot_baibot_config_initial_global_config_handler_image_generation: null
|
||||
|
||||
**Note**: these are initial defaults for the bot's global configuration. As such, changing any of these values subsequently has no effect on the bot's behavior. **Once initially configured the global configuration cannot be managed Ansible**, but only via bot commands.
|
||||
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
@ -407,7 +395,6 @@ Send `!bai help` to the room at any time to see the bot's help menu for addition
|
||||
|
||||
You can also refer to the upstream [baibot](https://github.com/etkecc/baibot) project's documentation.
|
||||
|
||||
|
||||
## Debugging
|
||||
|
||||
As with all other services, you can find service logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by running something like `journalctl -fu matrix-bot-baibot`
|
||||
|
||||
@ -20,14 +20,12 @@ You can use the playbook to [register a new user](registering-users.md):
|
||||
ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.chatgpt password=PASSWORD_FOR_THE_BOT admin=no' --tags=register-user
|
||||
```
|
||||
|
||||
|
||||
## 2. Get an access token and create encryption keys
|
||||
|
||||
Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
|
||||
|
||||
To make sure the bot can read encrypted messages, it will need an encryption key, just like any other new user. While obtaining the access token, follow the prompts to setup a backup key. More information can be found in the [Element documentation](https://element.io/help#encryption6).
|
||||
|
||||
|
||||
## 3. Adjusting the playbook configuration
|
||||
|
||||
Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
|
||||
@ -53,7 +51,6 @@ matrix_bot_chatgpt_matrix_bot_prompt_prefix: 'Instructions:\nYou are ChatGPT, a
|
||||
|
||||
You will need to get tokens for ChatGPT.
|
||||
|
||||
|
||||
## 4. Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
@ -6,7 +6,6 @@ See the project's [documentation](https://github.com/the-draupnir-project/Draupn
|
||||
|
||||
This documentation page is about installing Draupnir in bot mode. As an alternative, you can run a multi-instance Draupnir deployment by installing [Draupnir in appservice mode](./configuring-playbook-appservice-draupnir-for-all.md) (called Draupnir-for-all) instead.
|
||||
|
||||
|
||||
If your migrating from Mjolnir skip to step 5b.
|
||||
|
||||
## 1. Register the bot account
|
||||
@ -25,12 +24,10 @@ ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.draupni
|
||||
|
||||
If you would like Draupnir to be able to deactivate users, move aliases, shutdown rooms, show abuse reports ([see below](#abuse-reports)), etc then it must be a server admin so you need to change `admin=no` to `admin=yes` in the command above.
|
||||
|
||||
|
||||
## 2. Get an access token
|
||||
|
||||
Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
|
||||
|
||||
|
||||
## 3. Make sure the account is free from rate limiting
|
||||
|
||||
You will need to prevent Synapse from rate limiting the bot's account. This is not an optional step. If you do not do this step Draupnir will crash. This can be done using Synapse's [admin API](https://matrix-org.github.io/synapse/latest/admin_api/user_admin_api.html#override-ratelimiting-for-users). Please ask for help if you are uncomfortable with these steps or run into issues.
|
||||
@ -39,8 +36,6 @@ If your Synapse Admin API is exposed to the internet for some reason like runnin
|
||||
|
||||
The following command works on semi up to date Windows 10 installs and All Windows 11 installations and other systems that ship curl. `curl --header "Authorization: Bearer <access_token>" -X POST https://matrix.example.com/_synapse/admin/v1/users/@example:example.com/override_ratelimit` Replace `@example:example.com` with the MXID of your Draupnir and example.com with your homeserver domain. You can easily obtain an access token for a homeserver admin account the same way you can obtain an access token for Draupnir itself. If you made Draupnir Admin you can just use the Draupnir token.
|
||||
|
||||
|
||||
|
||||
## 4. Create a management room
|
||||
|
||||
Using your own account, create a new invite only room that you will use to manage the bot. This is the room where you will see the status of the bot and where you will send commands to the bot, such as the command to ban a user from another room. Anyone in this room can control the bot so it is important that you only invite trusted users to this room.
|
||||
@ -51,7 +46,6 @@ Once you have created the room you need to copy the room ID so you can tell the
|
||||
|
||||
Finally invite the `@bot.draupnir:example.com` account you created earlier into the room.
|
||||
|
||||
|
||||
## 5. Adjusting the playbook configuration
|
||||
|
||||
Decide whether you want Draupnir to be capable of operating in end-to-end encrypted (E2EE) rooms. This includes the management room and the moderated rooms. To support E2EE, Draupnir needs to [use Pantalaimon](configuring-playbook-pantalaimon.md).
|
||||
@ -200,7 +194,6 @@ To **enable a given protection**, send a command like this: `!draupnir enable PR
|
||||
|
||||
To **disable a given protection**, send a command like this: `!draupnir disable PROTECTION_NAME` (e.g. `!draupnir disable JoinWaveShortCircuit`).
|
||||
|
||||
|
||||
## Extending the configuration
|
||||
|
||||
You can configure additional options by adding the `matrix_bot_draupnir_configuration_extension_yaml` variable to your `inventory/host_vars/matrix.example.com/vars.yml` file.
|
||||
|
||||
@ -8,7 +8,6 @@ Go-NEB is a Matrix bot written in Go. It is the successor to Matrix-NEB, the ori
|
||||
|
||||
See the project's [documentation](https://github.com/matrix-org/go-neb) to learn what it does and why it might be useful to you.
|
||||
|
||||
|
||||
## Registering the bot user
|
||||
|
||||
The playbook does not automatically create users for you. The bot requires at least 1 access token to be able to connect to your homeserver.
|
||||
@ -25,7 +24,6 @@ ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.go-neb
|
||||
|
||||
Once the user is created you can [obtain an access token](obtaining-access-tokens.md).
|
||||
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
To enable Go-NEB, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
|
||||
@ -6,7 +6,6 @@ It's a bot you can use to setup **your own helpdesk on matrix**
|
||||
|
||||
See the project's [documentation](https://github.com/etkecc/honoroit#how-it-looks-like) to learn what it does with screenshots and why it might be useful to you.
|
||||
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
To enable Honoroit, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
|
||||
@ -6,7 +6,6 @@ The bot allows you to easily **create and manage registration tokens** aka. invi
|
||||
|
||||
See the project's [documentation](https://github.com/moan0s/matrix-registration-bot#supported-commands) to learn what it does and why it might be useful to you.
|
||||
|
||||
|
||||
## Configuration
|
||||
|
||||
To enable the bot, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
|
||||
@ -6,7 +6,6 @@ It's a bot you can use to **schedule one-off & recurring reminders and alarms**.
|
||||
|
||||
See the project's [documentation](https://github.com/anoadragon453/matrix-reminder-bot#usage) to learn what it does and why it might be useful to you.
|
||||
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
@ -24,7 +23,6 @@ matrix_bot_matrix_reminder_bot_matrix_user_password: PASSWORD_FOR_THE_BOT
|
||||
matrix_bot_matrix_reminder_bot_reminders_timezone: Europe/London
|
||||
```
|
||||
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
@ -4,7 +4,6 @@ The playbook can install and configure the [Mjolnir](https://github.com/matrix-o
|
||||
|
||||
See the project's [documentation](https://github.com/matrix-org/mjolnir) to learn what it does and why it might be useful to you.
|
||||
|
||||
|
||||
## 1. Register the bot account
|
||||
|
||||
The playbook does not automatically create users for you. The bot requires an access token to be able to connect to your homeserver.
|
||||
@ -21,12 +20,10 @@ ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.mjolnir
|
||||
|
||||
If you would like Mjolnir to be able to deactivate users, move aliases, shutdown rooms, etc then it must be a server admin so you need to change `admin=no` to `admin=yes` in the command above.
|
||||
|
||||
|
||||
## 2. Get an access token
|
||||
|
||||
Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
|
||||
|
||||
|
||||
## 3. Make sure the account is free from rate limiting
|
||||
|
||||
You will need to prevent Synapse from rate limiting the bot's account. This is not an optional step. If you do not do this step Mjolnir will crash. This can be done using Synapse's [admin API](https://matrix-org.github.io/synapse/latest/admin_api/user_admin_api.html#override-ratelimiting-for-users). Please ask for help if you are uncomfortable with these steps or run into issues.
|
||||
@ -45,7 +42,6 @@ Once you have created the room you need to copy the room ID so you can tell the
|
||||
|
||||
Finally invite the `@bot.mjolnir:example.com` account you created earlier into the room.
|
||||
|
||||
|
||||
## 5. Adjusting the playbook configuration
|
||||
|
||||
Decide whether you want Mjolnir to be capable of operating in end-to-end encrypted (E2EE) rooms. This includes the management room and the moderated rooms. To support E2EE, Mjolnir needs to [use Pantalaimon](configuring-playbook-pantalaimon.md).
|
||||
@ -105,7 +101,6 @@ matrix_bot_mjolnir_management_room: "ROOM_ID_FROM_STEP_4_GOES_HERE"
|
||||
|
||||
Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
|
||||
|
||||
|
||||
```yaml
|
||||
matrix_synapse_ext_spam_checker_mjolnir_antispam_enabled: true
|
||||
matrix_synapse_ext_spam_checker_mjolnir_antispam_config_block_invites: true
|
||||
@ -114,7 +109,6 @@ matrix_synapse_ext_spam_checker_mjolnir_antispam_config_block_usernames: false
|
||||
matrix_synapse_ext_spam_checker_mjolnir_antispam_config_ban_lists: []
|
||||
```
|
||||
|
||||
|
||||
## 7. Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
@ -15,6 +15,7 @@ matrix_beeper_linkedin_enabled: true
|
||||
There are some additional things you may wish to configure about the bridge before you continue.
|
||||
|
||||
Encryption support is off by default. If you would like to enable encryption, add the following to your `vars.yml` file:
|
||||
|
||||
```yaml
|
||||
matrix_beeper_linkedin_configuration_extension_yaml: |
|
||||
bridge:
|
||||
@ -24,6 +25,7 @@ matrix_beeper_linkedin_configuration_extension_yaml: |
|
||||
```
|
||||
|
||||
If you would like to be able to administrate the bridge from your account it can be configured like this:
|
||||
|
||||
```yaml
|
||||
matrix_beeper_linkedin_configuration_extension_yaml: |
|
||||
bridge:
|
||||
@ -58,7 +60,6 @@ Enabling [Appservice Double Puppet](configuring-playbook-appservice-double-puppe
|
||||
|
||||
Enabling double puppeting by enabling the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service works at the time of writing, but is deprecated and will stop working in the future.
|
||||
|
||||
|
||||
## Usage
|
||||
|
||||
You then need to start a chat with `@linkedinbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
|
||||
@ -69,7 +70,6 @@ If you run into trouble, check the [Troubleshooting](#troubleshooting) section b
|
||||
|
||||
After successfully enabling bridging, you may wish to [set up Double Puppeting](#set-up-double-puppeting-by-enabling-appservice-double-puppet-or-shared-secret-auth), if you haven't already done so.
|
||||
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Bridge asking for 2FA even if you don't have 2FA enabled
|
||||
|
||||
@ -8,7 +8,6 @@ See the project's [documentation](https://matrix-org.github.io/matrix-hookshot/l
|
||||
|
||||
**Note**: the playbook also supports [matrix-appservice-webhooks](configuring-playbook-bridge-appservice-webhooks.md), which however was deprecated by its author.
|
||||
|
||||
|
||||
## Setup Instructions
|
||||
|
||||
Refer to the [official instructions](https://matrix-org.github.io/matrix-hookshot/latest/setup.html) to learn what the individual options do.
|
||||
@ -41,7 +40,6 @@ Refer to [Hookshot's documentation](https://matrix-org.github.io/matrix-hookshot
|
||||
|
||||
**Important**: Note that the different listeners are bound to certain paths which might differ from those assumed by the hookshot documentation, see [URLs for bridges setup](#urls-for-bridges-setup) below.
|
||||
|
||||
|
||||
## More setup documentation
|
||||
|
||||
### URLs for bridges setup
|
||||
@ -72,6 +70,7 @@ The GitHub bridge requires you to install a private key file. This can be done i
|
||||
- use the [`aux` role](https://github.com/mother-of-all-self-hosting/ansible-role-aux) to copy the file from an arbitrary path on your ansible client to the correct path on the server.
|
||||
|
||||
To use the `aux` role, make sure the `matrix_hookshot_github_private_key` variable is empty. Then add the following additional configuration:
|
||||
|
||||
```yaml
|
||||
aux_file_definitions:
|
||||
- dest: "{{ matrix_hookshot_base_path }}/{{ matrix_hookshot_github_private_key_file }}"
|
||||
@ -80,6 +79,7 @@ aux_file_definitions:
|
||||
owner: "{{ matrix_user_username }}"
|
||||
group: "{{ matrix_user_groupname }}"
|
||||
```
|
||||
|
||||
For more information, see the documentation in the [default configuration of the aux role](https://github.com/mother-of-all-self-hosting/ansible-role-aux/blob/main/defaults/main.yml).
|
||||
|
||||
### Provisioning API
|
||||
|
||||
@ -8,7 +8,6 @@ The playbook can install and configure [mautrix-discord](https://github.com/maut
|
||||
|
||||
See the project's [documentation](https://docs.mau.fi/bridges/go/discord/index.html) to learn what it does and why it might be useful to you.
|
||||
|
||||
|
||||
## Prerequisites
|
||||
|
||||
There are 2 ways to login to discord using this bridge, either by [scanning a QR code](#method-1-login-using-qr-code-recommended) using the Discord mobile app **or** by using a [Discord token](#method-2-login-using-discord-token-not-recommended).
|
||||
|
||||
@ -23,6 +23,7 @@ matrix_mautrix_facebook_enabled: true
|
||||
There are some additional things you may wish to configure about the bridge before you continue.
|
||||
|
||||
Encryption support is off by default. If you would like to enable encryption, add the following to your `vars.yml` file:
|
||||
|
||||
```yaml
|
||||
matrix_mautrix_facebook_configuration_extension_yaml: |
|
||||
bridge:
|
||||
@ -32,6 +33,7 @@ matrix_mautrix_facebook_configuration_extension_yaml: |
|
||||
```
|
||||
|
||||
If you would like to be able to administrate the bridge from your account it can be configured like this:
|
||||
|
||||
```yaml
|
||||
matrix_mautrix_facebook_configuration_extension_yaml: |
|
||||
bridge:
|
||||
|
||||
@ -61,7 +61,6 @@ Enabling [Appservice Double Puppet](configuring-playbook-appservice-double-puppe
|
||||
|
||||
Enabling double puppeting by enabling the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service works at the time of writing, but is deprecated and will stop working in the future.
|
||||
|
||||
|
||||
#### Method 2: manually, by asking each user to provide a working access token
|
||||
|
||||
When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
|
||||
|
||||
@ -17,6 +17,7 @@ matrix_mautrix_instagram_enabled: true
|
||||
There are some additional things you may wish to configure about the bridge before you continue.
|
||||
|
||||
Encryption support is off by default. If you would like to enable encryption, add the following to your `vars.yml` file:
|
||||
|
||||
```yaml
|
||||
matrix_mautrix_instagram_configuration_extension_yaml: |
|
||||
bridge:
|
||||
@ -26,6 +27,7 @@ matrix_mautrix_instagram_configuration_extension_yaml: |
|
||||
```
|
||||
|
||||
If you would like to be able to administrate the bridge from your account it can be configured like this:
|
||||
|
||||
```yaml
|
||||
# The easy way. The specified Matrix user ID will be made an admin of all bridges
|
||||
matrix_admin: "@YOUR_USERNAME:{{ matrix_domain }}"
|
||||
|
||||
@ -48,6 +48,7 @@ Different levels of permission can be granted to users:
|
||||
The permissions are following the sequence: nothing < `relay` < `user` < `admin`.
|
||||
|
||||
The default permissions are set via `matrix_mautrix_meta_instagram_bridge_permissions_default` and are somewhat like this:
|
||||
|
||||
```yaml
|
||||
matrix_mautrix_meta_instagram_bridge_permissions_default:
|
||||
'*': relay
|
||||
|
||||
@ -48,7 +48,6 @@ You may switch the mode via the `matrix_mautrix_meta_messenger_meta_mode` variab
|
||||
|
||||
Note that switching the mode (especially between `facebook*` and `messenger`) will intentionally make the bridge use another database (`matrix_mautrix_meta_facebook` or `matrix_mautrix_meta_messenger`) to isolate the 2 instances. Switching between Tor and non-Tor may be possible without dataloss, but your mileage may vary. Before switching to a new mode, you may wish to de-configure the old one (send `help` to the bridge bot and unbridge your portals, etc.).
|
||||
|
||||
|
||||
### Bridge permissions
|
||||
|
||||
By default, any user on your homeserver will be able to use the bridge.
|
||||
@ -62,6 +61,7 @@ Different levels of permission can be granted to users:
|
||||
The permissions are following the sequence: nothing < `relay` < `user` < `admin`.
|
||||
|
||||
The default permissions are set via `matrix_mautrix_meta_messenger_bridge_permissions_default` and are somewhat like this:
|
||||
|
||||
```yaml
|
||||
matrix_mautrix_meta_messenger_bridge_permissions_default:
|
||||
'*': relay
|
||||
|
||||
@ -41,6 +41,7 @@ Different levels of permission can be granted to users:
|
||||
The permissions are following the sequence: nothing < relay < user < admin.
|
||||
|
||||
The default permissions are set as follows:
|
||||
|
||||
```yaml
|
||||
permissions:
|
||||
'*': relay
|
||||
@ -48,6 +49,7 @@ permissions:
|
||||
```
|
||||
|
||||
If you want to augment the preset permissions, you might want to set the additional permissions with the following settings in your `vars.yml` file:
|
||||
|
||||
```yaml
|
||||
matrix_mautrix_signal_configuration_extension_yaml: |
|
||||
bridge:
|
||||
@ -58,6 +60,7 @@ matrix_mautrix_signal_configuration_extension_yaml: |
|
||||
This will add the admin permission to the specific user, while keeping the default permissions.
|
||||
|
||||
In case you want to replace the default permissions settings **completely**, populate the following item within your `vars.yml` file:
|
||||
|
||||
```yaml
|
||||
matrix_mautrix_signal_bridge_permissions:
|
||||
'@ADMIN:example.com': admin
|
||||
|
||||
@ -10,7 +10,6 @@ See the project's [documentation](https://docs.mau.fi/bridges/go/slack/index.htm
|
||||
|
||||
See the [features and roadmap](https://github.com/mautrix/slack/blob/main/ROADMAP.md) for more information.
|
||||
|
||||
|
||||
## Prerequisites
|
||||
|
||||
For using this bridge, you would need to authenticate by **providing your username and password** (legacy) or by using a **token login**. See more information in the [docs](https://docs.mau.fi/bridges/go/slack/authentication.html).
|
||||
|
||||
@ -52,6 +52,7 @@ matrix_mautrix_telegram_configuration_extension_yaml: |
|
||||
```
|
||||
|
||||
You might also want to give permissions to administrate the bot:
|
||||
|
||||
```yaml
|
||||
matrix_mautrix_telegram_configuration_extension_yaml: |
|
||||
bridge:
|
||||
@ -62,6 +63,7 @@ matrix_mautrix_telegram_configuration_extension_yaml: |
|
||||
More details about permissions in this example: https://github.com/mautrix/telegram/blob/master/mautrix_telegram/example-config.yaml#L410
|
||||
|
||||
If you like to exclude all groups from syncing and use the Telgeram-Bridge only for direct chats, you can add the following additional playbook configuration:
|
||||
|
||||
```yaml
|
||||
matrix_mautrix_telegram_filter_mode: whitelist
|
||||
```
|
||||
|
||||
@ -19,7 +19,6 @@ If you don't open these ports, you will still be able to send emails, but not re
|
||||
|
||||
These port numbers are configurable via the `matrix_postmoogle_smtp_host_bind_port` and `matrix_postmoogle_submission_host_bind_port` variables, but other email servers will try to deliver on these default (standard) ports, so changing them is of little use.
|
||||
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
|
||||
@ -8,7 +8,6 @@ Cinny is a web client focusing primarily on simple, elegant and secure interface
|
||||
|
||||
- [app.cinny.in](https://app.cinny.in), hosted by the [Cinny](https://cinny.in/) developers
|
||||
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
To enable Cinny, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
|
||||
@ -7,7 +7,6 @@ By default, this playbook installs the [Element Web](https://github.com/element-
|
||||
- [app.element.io](https://app.element.io/), hosted by [Element](https://element.io/)
|
||||
- [app.etke.cc](https://app.etke.cc/), hosted by [etke.cc](https://etke.cc/)
|
||||
|
||||
|
||||
## Disabling Element Web
|
||||
|
||||
If you'd like for the playbook to not install Element Web (or to uninstall it if it was previously installed), add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
@ -16,7 +15,6 @@ If you'd like for the playbook to not install Element Web (or to uninstall it if
|
||||
matrix_client_element_enabled: false
|
||||
```
|
||||
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
The playbook provides some customization variables you could use to change Element Web's settings.
|
||||
@ -33,7 +31,6 @@ Alternatively, **if there is no pre-defined variable** for an Element Web settin
|
||||
|
||||
- or, if extending the configuration is still not powerful enough for your needs, you can **override the configuration completely** using `matrix_client_element_configuration_default` (or `matrix_client_element_configuration`). You can find information about this in [`roles/custom/matrix-client-element/defaults/main.yml`](../roles/custom/matrix-client-element/defaults/main.yml).
|
||||
|
||||
|
||||
### Themes
|
||||
|
||||
To change the look of Element Web, you can define your own themes manually by using the `matrix_client_element_setting_defaults_custom_themes` setting.
|
||||
|
||||
@ -27,7 +27,6 @@ Since it is difficult to create the first user account on Conduit (see [famedly/
|
||||
5. Run the playbook again (`ansible-playbook -i inventory/hosts setup.yml --tags=setup-conduit,start` would be enough this time)
|
||||
6. You can now use your server safely. Additional users can be created by messaging the internal Conduit bot
|
||||
|
||||
|
||||
## Configuring bridges / appservices
|
||||
|
||||
Automatic appservice setup is currently unsupported when using Conduit. After setting up the service as usual you may notice that it is unable to start.
|
||||
@ -36,7 +35,6 @@ You will have to manually register appservices using the the [register-appservic
|
||||
|
||||
Find the `registration.yaml` in the `/matrix` directory, for example `/matrix/mautrix-signal/bridge/registration.yaml`, then pass the content to Conduit:
|
||||
|
||||
|
||||
@conduit:example.com: register-appservice
|
||||
```
|
||||
as_token: <token>
|
||||
|
||||
@ -30,8 +30,6 @@ Alternatively, **if there is no pre-defined variable** for a Dendrite setting yo
|
||||
|
||||
- or, if extending the configuration is still not powerful enough for your needs, you can **override the configuration completely** using `matrix_dendrite_configuration` (or `matrix_dendrite_configuration_yaml`). You can find information about this in [`roles/custom/matrix-dendrite/defaults/main.yml`](../roles/custom/matrix-dendrite/defaults/main.yml).
|
||||
|
||||
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
@ -90,7 +90,6 @@ By default Dimension will use [jitsi.riot.im](https://jitsi.riot.im/) as the `co
|
||||
|
||||
In the interim until the above limitation is resolved, an admin user needs to configure the domain via the admin ui once dimension is running. In Element Web, go to *Manage Integrations* → *Settings* → *Widgets* → *Jitsi Conference Settings* and set *Jitsi Domain* and *Jitsi Script URL* appropriately.
|
||||
|
||||
|
||||
## Additional features
|
||||
|
||||
To use a more custom configuration, you can define a `matrix_dimension_configuration_extension_yaml` string variable and put your configuration in it. To learn more about how to do this, refer to the information about `matrix_dimension_configuration_extension_yaml` in the [default variables file](../roles/custom/matrix-dimension/defaults/main.yml) of the Dimension component.
|
||||
|
||||
@ -10,12 +10,10 @@ By default, emails are sent from `matrix@matrix.example.com`, as specified by th
|
||||
|
||||
💡 To improve deliverability, we recommend [relaying email through another SMTP server](#relaying-email-through-another-smtp-server) anyway.
|
||||
|
||||
|
||||
## Firewall settings
|
||||
|
||||
No matter whether you send email directly (the default) or you relay email through another host (see how below), you'll probably need to allow outgoing traffic for TCP ports 25/587 (depending on configuration).
|
||||
|
||||
|
||||
## Relaying email through another SMTP server
|
||||
|
||||
If you'd like to relay email through another SMTP server, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
|
||||
@ -32,8 +30,8 @@ exim_relay_relay_auth_password: "some-password"
|
||||
|
||||
**Note**: only the secure submission protocol (using `STARTTLS`, usually on port `587`) is supported. **SMTPS** (encrypted SMTP, usually on port `465`) **is not supported**.
|
||||
|
||||
|
||||
### Configuations for sending emails using Sendgrid
|
||||
|
||||
An easy and free SMTP service to set up is [Sendgrid](https://sendgrid.com/), the free tier allows for up to 100 emails per day to be sent. In the settings below you can provide any email for `exim_relay_sender_address`.
|
||||
|
||||
The only other thing you need to change is the `exim_relay_relay_auth_password`, which you can generate at https://app.sendgrid.com/settings/api_keys. The API key password looks something like `SG.955oW1mLSfwds7i9Yd6IA5Q.q8GTaB8q9kGDzasegdG6u95fQ-6zkdwrPP8bOeuI`.
|
||||
|
||||
@ -6,7 +6,6 @@ The playbook can install and configure [email2matrix](https://github.com/devture
|
||||
|
||||
See the project's [documentation](https://github.com/devture/email2matrix/blob/master/docs/README.md) to learn what it does and why it might be useful to you.
|
||||
|
||||
|
||||
## Preparation
|
||||
|
||||
### DNS configuration
|
||||
|
||||
@ -33,7 +33,6 @@ etherpad_hostname: "{{ matrix_server_fqn_matrix }}"
|
||||
etherpad_path_prefix: /etherpad
|
||||
```
|
||||
|
||||
|
||||
## Adjusting DNS records
|
||||
|
||||
Once you've decided on the domain and path, **you may need to adjust your DNS** records to point the Etherpad domain to the Matrix server.
|
||||
@ -67,35 +66,30 @@ The Etherpad UI should be available at `https://etherpad.example.com`, while the
|
||||
|
||||
If you've [decided on another hostname or path-prefix](#adjusting-the-etherpad-url) (e.g. `https://matrix.example.com/etherpad`), adjust these URLs accordingly before usage.
|
||||
|
||||
|
||||
### Managing / Deleting old pads
|
||||
|
||||
If you want to manage and remove old unused pads from Etherpad, you will first need to able Admin access as described above.
|
||||
|
||||
Then from the plugin manager page (`https://etherpad.example.com/admin/plugins`, install the `adminpads2` plugin. Once installed, you should have a "Manage pads" section in the Admin web-UI.
|
||||
|
||||
|
||||
### How to use Etherpad widgets without an integration manager (like Dimension)
|
||||
|
||||
This is how it works in Element Web, it might work quite similar with other clients:
|
||||
|
||||
To integrate a standalone Etherpad in a room, create your pad by visiting `https://etherpad.example.com`. When the pad opens, copy the URL and send a command like this to the room: `/addwidget URL`. You will then find your integrated Etherpad within the right sidebar in the `Widgets` section.
|
||||
|
||||
|
||||
### Set Dimension default to the self-hosted Etherpad (optional)
|
||||
|
||||
If you decided to install [Dimension integration manager](configuring-playbook-dimension.md) alongside Etherpad, the Dimension administrator users can configure the default URL template.
|
||||
|
||||
The Dimension configuration menu can be accessed with the sprocket icon as you begin to add a widget to a room in Element Web. There you will find the Etherpad Widget Configuration action beneath the _Widgets_ tab.
|
||||
|
||||
|
||||
#### Removing the integrated Etherpad chat
|
||||
|
||||
If you wish to disable the Etherpad chat button, you can do it by appending `?showChat=false` to the end of the pad URL, or the template.
|
||||
|
||||
Example: `https://etherpad.example.com/p/$roomId_$padName?showChat=false`
|
||||
|
||||
|
||||
## Known issues
|
||||
|
||||
If your Etherpad widget fails to load, this might be due to Dimension generating a Pad name so long, the Etherpad app rejects it.
|
||||
|
||||
@ -16,7 +16,6 @@ matrix_synapse_federation_domain_whitelist:
|
||||
|
||||
If you wish to disable federation, you can do that with an empty list (`[]`), or better yet by completely disabling federation (see below).
|
||||
|
||||
|
||||
## Exposing the room directory over federation
|
||||
|
||||
By default, your server's public rooms directory is not exposed to other servers via federation.
|
||||
@ -27,7 +26,6 @@ If you wish to expose it, add this to your configuration file (`inventory/host_v
|
||||
matrix_synapse_allow_public_rooms_over_federation: true
|
||||
```
|
||||
|
||||
|
||||
## Disabling federation
|
||||
|
||||
To completely disable federation, isolating your server from the rest of the Matrix network, add this to your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`):
|
||||
@ -54,7 +52,6 @@ matrix_synapse_reverse_proxy_companion_federation_api_enabled: false
|
||||
|
||||
Why? This change could be useful for people running small Synapse instances on small severs/VPSes to avoid being impacted by a simple DOS/DDOS when bandwidth, RAM, an CPU resources are limited and if your hosting provider does not provide a DOS/DDOS protection.
|
||||
|
||||
|
||||
The following changes in the configuration file (`inventory/host_vars/matrix.example.com/vars.yml`) will allow this and make it possible to proxy the federation through a CDN such as CloudFlare or any other:
|
||||
|
||||
```yaml
|
||||
|
||||
@ -6,7 +6,6 @@ Jitsi installation is **not enabled by default**, because it's not a core compon
|
||||
|
||||
The setup done by the playbook is very similar to [docker-jitsi-meet](https://github.com/jitsi/docker-jitsi-meet). You can refer to the documentation there for many of the options here.
|
||||
|
||||
|
||||
## Prerequisites
|
||||
|
||||
You may need to open the following ports to your server:
|
||||
@ -14,7 +13,6 @@ You may need to open the following ports to your server:
|
||||
- `4443/tcp` - RTP media fallback over TCP
|
||||
- `10000/udp` - RTP media over UDP. Depending on your firewall/NAT setup, incoming RTP packets on port `10000` may have the external IP of your firewall as destination address, due to the usage of STUN in JVB (see [`jitsi_jvb_stun_servers`](https://github.com/mother-of-all-self-hosting/ansible-role-jitsi/blob/main/defaults/main.yml)).
|
||||
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
To enable Jitsi, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
@ -114,7 +112,6 @@ jitsi_ldap_start_tls: false
|
||||
|
||||
For more information refer to the [docker-jitsi-meet](https://github.com/jitsi/docker-jitsi-meet#authentication-using-ldap) and the [saslauthd `LDAP_SASLAUTHD`](https://github.com/winlibs/cyrus-sasl/blob/master/saslauthd/LDAP_SASLAUTHD) documentation.
|
||||
|
||||
|
||||
## (Optional) Making your Jitsi server work on a LAN
|
||||
|
||||
By default the Jitsi Meet instance does not work with a client in LAN (Local Area Network), even if others are connected from WAN. There are no video and audio. In the case of WAN to WAN everything is ok.
|
||||
@ -172,6 +169,7 @@ By default, a single JVB ([Jitsi VideoBridge](https://github.com/jitsi/jitsi-vid
|
||||
There is an ansible playbook that can be run with the following tag: `ansible-playbook -i inventory/hosts --limit jitsi_jvb_servers jitsi_jvb.yml --tags=common,setup-additional-jitsi-jvb,start`
|
||||
|
||||
For this role to work you will need an additional section in the ansible hosts file with the details of the JVB hosts, for example:
|
||||
|
||||
```INI
|
||||
[jitsi_jvb_servers]
|
||||
<your jvb hosts> ansible_host=<ip address of the jvb host>
|
||||
@ -292,7 +290,6 @@ You can use the self-hosted Jitsi server in multiple ways:
|
||||
|
||||
**Note**: Element apps on mobile devices currently [don't support joining meetings on a self-hosted Jitsi server](https://github.com/element-hq/riot-web/blob/601816862f7d84ac47547891bd53effa73d32957/docs/jitsi.md#mobile-app-support).
|
||||
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Rebuilding your Jitsi installation
|
||||
|
||||
@ -21,7 +21,6 @@ matrix_synapse_ext_password_provider_ldap_bind_password: ""
|
||||
matrix_synapse_ext_password_provider_ldap_filter: ""
|
||||
```
|
||||
|
||||
|
||||
## Authenticating only using a password provider
|
||||
|
||||
If you wish for users to **authenticate only against configured password providers** (like this one), **without consulting Synapse's local database**, feel free to disable it:
|
||||
@ -30,12 +29,10 @@ If you wish for users to **authenticate only against configured password provide
|
||||
matrix_synapse_password_config_localdb_enabled: false
|
||||
```
|
||||
|
||||
|
||||
## Using ma1sd Identity Server for authentication
|
||||
|
||||
If you wish to use the ma1sd Identity Server for LDAP authentication instead of [matrix-synapse-ldap3](https://github.com/matrix-org/matrix-synapse-ldap3) consult [Adjusting ma1sd Identity Server configuration](configuring-playbook-ma1sd.md#authentication).
|
||||
|
||||
|
||||
## Handling user registration
|
||||
|
||||
If you wish for users to also be able to make new registrations against LDAP, you may **also** wish to [set up the ldap-registration-proxy](configuring-playbook-matrix-ldap-registration-proxy.md).
|
||||
|
||||
@ -51,7 +51,6 @@ Still, ma1sd can do much more. You can refer to the [ma1sd website](https://gith
|
||||
|
||||
To use a more custom configuration, you can define a `matrix_ma1sd_configuration_extension_yaml` string variable and put your configuration in it. To learn more about how to do this, refer to the information about `matrix_ma1sd_configuration_extension_yaml` in the [default variables file](../roles/custom/matrix-ma1sd/defaults/main.yml) of the ma1sd component.
|
||||
|
||||
|
||||
#### Customizing email templates
|
||||
|
||||
If you'd like to change the default email templates used by ma1sd, take a look at the `matrix_ma1sd_threepid_medium_email_custom_` variables (in the `roles/custom/matrix-ma1sd/defaults/main.yml` file.
|
||||
@ -72,7 +71,6 @@ To use the [Registration](https://github.com/ma1uta/ma1sd/blob/master/docs/featu
|
||||
|
||||
**Note**: For this to work, either the homeserver needs to [federate](configuring-playbook-federation.md) or the `openid` APIs need to exposed on the federation port. When federation is disabled and ma1sd is enabled, we automatically expose the `openid` APIs (only!) on the federation port. Make sure the federation port (usually `https://matrix.example.com:8448`) is whitelisted in your firewall (even if you don't actually use/need federation).
|
||||
|
||||
|
||||
#### Authentication
|
||||
|
||||
[Authentication](https://github.com/ma1uta/ma1sd/blob/master/docs/features/authentication.md) provides the possibility to use your own [Identity Stores](https://github.com/ma1uta/ma1sd/blob/master/docs/stores/README.md) (for example LDAP) to authenticate users on your Homeserver.
|
||||
|
||||
@ -12,7 +12,6 @@ Matrix Authentication Service is an implementation of [MSC3861: Next-generation
|
||||
|
||||
**If you've already been using Synapse** and have user accounts in its database, you can [migrate to Matrix Authentication Service](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service).
|
||||
|
||||
|
||||
## Reasons to use Matrix Authentication Service
|
||||
|
||||
You may be wondering whether you should make the switch to Matrix Authentication Service (MAS) or keep using your existing authentication flow via Synapse (password-based or [OIDC](./configuring-playbook-synapse.md#synapse--openid-connect-for-single-sign-on)-enabled).
|
||||
@ -33,7 +32,6 @@ Below, we'll try to **highlight some potential reasons for switching** to Matrix
|
||||
|
||||
- To reap some of the security benefits that Matrix Authentication Service offers, as outlined in the [Better authentication, session management and permissions in Matrix](https://matrix.org/blog/2023/09/better-auth/) article.
|
||||
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- ⚠️ the [Synapse](configuring-playbook-synapse.md) homeserver implementation (which is the default for this playbook). Other homeserver implementations ([Dendrite](./configuring-playbook-dendrite.md), [Conduit](./configuring-playbook-conduit.md), etc.) do not support integrating wtih Matrix Authentication Service yet.
|
||||
@ -42,7 +40,6 @@ Below, we'll try to **highlight some potential reasons for switching** to Matrix
|
||||
|
||||
- ❌ **disabling all password providers** for Synapse (things like [shared-secret-auth](./configuring-playbook-shared-secret-auth.md), [rest-auth](./configuring-playbook-rest-auth.md), [LDAP auth](./configuring-playbook-ldap-auth.md), etc.) More details about this are available in the [Expectations](#expectations) section below.
|
||||
|
||||
|
||||
## Expectations
|
||||
|
||||
This section details what you can expect when switching to the Matrix Authentication Service (MAS).
|
||||
@ -84,8 +81,6 @@ This section details what you can expect when switching to the Matrix Authentica
|
||||
|
||||
- ✅ Users that are prepared by the playbook (for bots, bridges, etc.) will continue to be registered automatically as expected. The playbook automatically does the right thing regardless of homeserver implementation (Synapse, Dendrite, etc.) and whether MAS is enabled or not. When MAS is enabled, the playbook will forward user-registration requests to MAS.
|
||||
|
||||
|
||||
|
||||
## Installation flows
|
||||
|
||||
### New homeserver
|
||||
@ -102,7 +97,6 @@ For existing Synapse homeservers:
|
||||
|
||||
- then follow the [Migrating an existing Synapse homeserver to Matrix Authentication Service](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service) instructions to perform the installation and migration
|
||||
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
To enable Matrix Authentication Service, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
@ -123,7 +117,6 @@ In the sub-sections that follow, we'll cover some additional configuration optio
|
||||
|
||||
There are many other configuration options available. Consult the [`defaults/main.yml` file](../roles/custom/matrix-authentication-service/defaults/main.yml) in the [matrix-authentication-service role](../roles/custom/matrix-authentication-service/) to discover them.
|
||||
|
||||
|
||||
### Adjusting the Matrix Authentication Service URL
|
||||
|
||||
By default, this playbook installs the Matrix Authentication Service on the `matrix.` subdomain, at the `/auth` path (https://matrix.example.com/auth). This makes it easy to install it, because it **doesn't require additional DNS records to be set up**. If that's okay, you can skip this section.
|
||||
@ -144,7 +137,6 @@ The [configuration above](#adjusting-the-playbook-configuration) instructs exist
|
||||
|
||||
This is done temporarily. The migration steps are described in more detail in the [Migrating an existing Synapse homeserver to Matrix Authentication Service](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service) section below.
|
||||
|
||||
|
||||
### Upstream OAuth2 configuration
|
||||
|
||||
To make Matrix Authentication Service delegate to an existing upstream OAuth 2.0/OIDC provider, you can use its [`upstream_oauth2.providers` setting](https://element-hq.github.io/matrix-authentication-service/reference/configuration.html#upstream_oauth2providers).
|
||||
@ -276,7 +268,6 @@ matrix_authentication_service_config_upstream_oauth2_providers:
|
||||
- go through the [migrating an existing homeserver](#migrating-an-existing-synapse-homeserver-to-matrix-authentication-service) process
|
||||
- remove all Synapse OIDC-related configuration (`matrix_synapse_oidc_*`) to prevent it being in conflict with the MAS OIDC configuration
|
||||
|
||||
|
||||
## Adjusting DNS records
|
||||
|
||||
If you've changed the default hostname, **you may need to adjust your DNS** records to point the Matrix Authentication Service domain to the Matrix server.
|
||||
@ -285,7 +276,6 @@ See [Configuring DNS](configuring-dns.md) for details about DNS changes.
|
||||
|
||||
If you've decided to use the default hostname, you won't need to do any extra DNS configuration.
|
||||
|
||||
|
||||
## Installing
|
||||
|
||||
Now that you've [adjusted the playbook configuration](#adjusting-the-playbook-configuration) and [your DNS records](#adjusting-dns-records), you can run the playbook with [playbook tags](playbook-tags.md) as below:
|
||||
@ -305,7 +295,6 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
|
||||
|
||||
💡 After installation, you should [verify that Matrix Authentication Service is installed correctly](#verify-that-matrix-authentication-service-is-installed-correctly).
|
||||
|
||||
|
||||
## Migrating an existing Synapse homeserver to Matrix Authentication Service
|
||||
|
||||
Our migration guide is loosely based on the upstream [Migrating an existing homeserver](https://element-hq.github.io/matrix-authentication-service/setup/migration.html) guide.
|
||||
@ -344,7 +333,6 @@ The installation + migration steps are like this:
|
||||
|
||||
6. [Verify that Matrix Authentication Service is installed correctly](#verify-that-matrix-authentication-service-is-installed-correctly)
|
||||
|
||||
|
||||
### Migrate your data from Synapse to Matrix Authentication Service using syn2mas
|
||||
|
||||
We **don't** ask you to [run the `syn2mas` migration advisor command](https://element-hq.github.io/matrix-authentication-service/setup/migration.html#run-the-migration-advisor), because it only gives you the green light if your Synapse configuration (`homeserver.yaml`) is configured in a way that's compatible with MAS (delegating authentication to MAS; disabling Synapse's password config; etc.). Until we migrate your data with the `syn2mas` tool, we intentionally avoid doing these changes to allow existing user sessions to work.
|
||||
@ -418,7 +406,6 @@ just run-tags matrix-authentication-service-syn2mas
|
||||
|
||||
Having performed a `syn2mas` migration once, trying to do it again will report errors for users that were already migrated (e.g. "Error: Unknown upstream provider oauth-delegated").
|
||||
|
||||
|
||||
## Verify that Matrix Authentication Service is installed correctly
|
||||
|
||||
After [installation](#installing), run the `doctor` subcommand of the [`mas-cli` command-line tool](https://element-hq.github.io/matrix-authentication-service/reference/cli/index.html) to verify that MAS is installed correctly.
|
||||
@ -453,14 +440,12 @@ This documentation page already mentions:
|
||||
|
||||
There are other sub-commands available. Run `/matrix/matrix-authentication-service/bin/mas-cli` to get an overview.
|
||||
|
||||
|
||||
## User registration
|
||||
|
||||
After Matrix Authentication Service is [installed](#installing), users need to be managed there (unless you're managing them in an [upstream OAuth2 provider](#upstream-oauth2-configuration)).
|
||||
|
||||
You can register users new users as described in the [Registering users](./registering-users.md) documentation (via `mas-cli manage register-user` or the Ansible playbook's `register-user` tag).
|
||||
|
||||
|
||||
## Working around email deliverability issues
|
||||
|
||||
Because Matrix Authentication Service [still insists](https://github.com/element-hq/matrix-authentication-service/issues/1505) on having a verified email address for each user, you may need to work around email deliverability issues if [your email-sending configuration](./configuring-playbook-email.md) is not working.
|
||||
|
||||
@ -14,7 +14,6 @@ If you decide that you'd like to let this playbook install it for you, you'd nee
|
||||
- (required) [set up the Shared Secret Auth password provider module](configuring-playbook-shared-secret-auth.md)
|
||||
- (optional, but encouraged) [set up the REST authentication password provider module](configuring-playbook-rest-auth.md)
|
||||
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
|
||||
|
||||
@ -30,6 +30,7 @@ By default, the media-repo will use the local filesystem for data storage. You c
|
||||
## Configuring the media-repo
|
||||
|
||||
Additional common configuration options:
|
||||
|
||||
```yaml
|
||||
|
||||
# The postgres database pooling options
|
||||
|
||||
@ -16,7 +16,6 @@ Use matrix-registration to **create unique registration links**, which people ca
|
||||
|
||||
- **a user registration page**, where people can use these registration tokens. By default, exposed at `https://matrix.example.com/matrix-registration`
|
||||
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
To enable matrix-registration, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
@ -71,7 +70,6 @@ It provides various [APIs](https://github.com/ZerataX/matrix-registration/wiki/a
|
||||
|
||||
We make the most common APIs easy to use via the playbook (see below).
|
||||
|
||||
|
||||
### Creating registration tokens
|
||||
|
||||
To **create a new user registration token (link)**, use this command:
|
||||
@ -86,7 +84,6 @@ The above command creates and returns a **one-time use** token, which **expires*
|
||||
|
||||
Share the unique registration link (generated by the command above) with users to let them register on your Matrix server.
|
||||
|
||||
|
||||
### Listing registration tokens
|
||||
|
||||
To **list the existing user registration tokens**, use this command:
|
||||
|
||||
@ -130,7 +130,6 @@ to `vars.yml` to control the logging level, where you may replace WARN with one
|
||||
|
||||
If you have issues with a service, and are requesting support, the higher levels of logging will generally be more helpful.
|
||||
|
||||
|
||||
## Usage
|
||||
|
||||
You then need to start a chat with `@SERVICENAMEbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
|
||||
@ -139,8 +138,6 @@ Send `login` to the bridge bot to get started. You can learn more here about aut
|
||||
|
||||
If you run into trouble, check the [Troubleshooting](#troubleshooting) section below.
|
||||
|
||||
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
For troubleshooting information with a specific bridge, please see the playbook documentation about it (some other document in in `docs/`) and the upstream ([mautrix](https://github.com/mautrix)) bridge documentation for that specific bridge.
|
||||
|
||||
@ -8,7 +8,6 @@ This role is intended to support UnifiedPush notifications for use with the Matr
|
||||
|
||||
**Note**: In contrast to push notifications using Google's FCM or Apple's APNs, the use of UnifiedPush allows each end-user to choose the push notification server that they prefer. As a consequence, deploying this ntfy server does not by itself ensure any particular user or device or client app will use it.
|
||||
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
To enable ntfy, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
@ -106,7 +105,6 @@ ntfy also has a web app to subscribe to and push to topics from the browser. Thi
|
||||
|
||||
The web app is disabled in this playbook by default as the expectation is that most users won't use it. You can either use the [official hosted one](https://ntfy.sh/app) (it supports using other public reachable ntfy instances) or host it yourself by setting `ntfy_web_root: "app"` and re-running Ansible.
|
||||
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
First check that the Matrix client app you are using supports UnifiedPush. There may well be different variants of the app.
|
||||
|
||||
@ -24,7 +24,6 @@ traefik_config_certificatesResolvers_acme_email: YOUR_EMAIL_ADDRESS
|
||||
|
||||
Traefik will manage SSL certificates for all services seamlessly.
|
||||
|
||||
|
||||
### Traefik managed by you
|
||||
|
||||
```yaml
|
||||
@ -132,7 +131,6 @@ There are 2 ways to go about it:
|
||||
|
||||
- (difficult) [Using no reverse-proxy on the Matrix side at all](#using-no-reverse-proxy-on-the-matrix-side-at-all) disabling the playbook-managed reverse-proxy (Traefik), exposing services one by one using `_host_bind_port` variables and forwarding traffic from your own webserver to those ports
|
||||
|
||||
|
||||
### Fronting the integrated reverse-proxy webserver with another reverse-proxy
|
||||
|
||||
This method is about leaving the integrated reverse-proxy webserver be, but making it not get in the way (using up important ports, trying to retrieve SSL certificates, etc.).
|
||||
@ -201,7 +199,6 @@ To put it another way:
|
||||
- `curl http://127.0.0.1:81` will result in a `404 - not found` error
|
||||
- but `curl -H 'Host: matrix.example.com' http://127.0.0.1:81` should work.
|
||||
|
||||
|
||||
### Using no reverse-proxy on the Matrix side at all
|
||||
|
||||
Instead of [Fronting the integrated reverse-proxy webserver with another reverse-proxy](#fronting-the-integrated-reverse-proxy-webserver-with-another-reverse-proxy), you can also go another way -- completely disabling the playbook-managed Traefik reverse-proxy. You would then need to reverse-proxy from your own webserver directly to each individual Matrix service.
|
||||
|
||||
@ -4,7 +4,6 @@ The playbook can install and configure [docker-postgres-backup-local](https://gi
|
||||
|
||||
For a more complete backup solution (one that includes not only Postgres, but also other configuration/data files), you may wish to look into [BorgBackup](configuring-playbook-backup-borg.md) instead.
|
||||
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
To enable Postgres backup, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
@ -15,7 +14,6 @@ postgres_backup_enabled: true
|
||||
|
||||
Refer to the table below for additional configuration variables and their default values.
|
||||
|
||||
|
||||
| Name | Default value | Description |
|
||||
| :-------------------------------- | :--------------------------- | :--------------------------------------------------------------- |
|
||||
|`postgres_backup_enabled`|`false`|Set to true to use [docker-postgres-backup-local](https://github.com/prodrigestivill/docker-postgres-backup-local) to create automatic database backups|
|
||||
@ -26,7 +24,6 @@ Refer to the table below for additional configuration variables and their defaul
|
||||
|`postgres_backup_base_path` | `"{{ matrix_base_data_path }}/postgres-backup"` | Base path for postgres-backup. Also see `postgres_backup_data_path` |
|
||||
|`postgres_backup_data_path` | `"{{ postgres_backup_base_path }}/data"` | Storage path for postgres-backup database backups |
|
||||
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
@ -78,14 +78,12 @@ Name | Description
|
||||
`grafana_anonymous_access`|By default you need to log in to see graphs. If you want to publicly share your graphs (e.g. when asking for help in [`#synapse:matrix.org`](https://matrix.to/#/#synapse:matrix.org?via=matrix.org&via=privacytools.io&via=mozilla.org)) you'll want to enable this option.
|
||||
`grafana_default_admin_user`<br>`grafana_default_admin_password`|By default Grafana creates a user with `admin` as the username and password. If you feel this is insecure and you want to change it beforehand, you can do that here
|
||||
|
||||
|
||||
## Security and privacy
|
||||
|
||||
Metrics and resulting graphs can contain a lot of information. This includes system specs but also usage patterns. This applies especially to small personal/family scale homeservers. Someone might be able to figure out when you wake up and go to sleep by looking at the graphs over time. Think about this before enabling anonymous access. And you should really not forget to change your Grafana password.
|
||||
|
||||
Most of our docker containers run with limited system access, but the `prometheus-node-exporter` has access to the host network stack and (readonly) root filesystem. This is required to report on them. If you don't like that, you can set `prometheus_node_exporter_enabled: false` (which is actually the default). You will still get Synapse metrics with this container disabled. Both of the dashboards will always be enabled, so you can still look at historical data after disabling either source.
|
||||
|
||||
|
||||
## Collecting metrics to an external Prometheus server
|
||||
|
||||
**If the integrated Prometheus server is enabled** (`prometheus_enabled: true`), metrics are collected by it from each service via communication that happens over the container network. Each service does not need to expose its metrics "publicly".
|
||||
@ -122,6 +120,7 @@ Name | Description
|
||||
If you are using workers (`matrix_synapse_workers_enabled: true`) and have enabled `matrix_synapse_metrics_proxying_enabled` as described above, the playbook will also automatically expose all Synapse worker threads' metrics to `https://matrix.example.com/metrics/synapse/worker/ID`, where `ID` corresponds to the worker `id` as exemplified in `matrix_synapse_workers_enabled_list`.
|
||||
|
||||
The playbook also generates an exemplary config file (`/matrix/synapse/external_prometheus.yml.template`) with all the correct paths which you can copy to your Prometheus server and adapt to your needs. Make sure to edit the specified `password_file` path and contents and path to your `synapse-v2.rules`. It will look a bit like this:
|
||||
|
||||
```yaml
|
||||
scrape_configs:
|
||||
- job_name: 'synapse'
|
||||
@ -148,7 +147,6 @@ scrape_configs:
|
||||
index: 18111
|
||||
```
|
||||
|
||||
|
||||
## More information
|
||||
|
||||
- [Enabling synapse-usage-exporter for Synapse usage statistics](configuring-playbook-synapse-usage-exporter.md)
|
||||
|
||||
@ -32,7 +32,6 @@ Name | Description
|
||||
`prometheus_postgres_exporter_database_password`| The 'password' for the user that the exporter uses to connect to the database. By default, this is auto-generated by the playbook
|
||||
`prometheus_postgres_exporter_container_labels_traefik_enabled`|If set to `true`, exposes the Postgres exporter metrics on `https://matrix.example.com/metrics/postgres-exporter` for usage with an [external Prometheus server](configuring-playbook-prometheus-grafana.md#collecting-metrics-to-an-external-prometheus-server). To password-protect the metrics, see `matrix_metrics_exposure_http_basic_auth_users` on that other documentation page.
|
||||
|
||||
|
||||
## More information
|
||||
|
||||
- [The PostgresSQL dashboard](https://grafana.com/grafana/dashboards/9628) (generic postgres dashboard)
|
||||
|
||||
@ -7,7 +7,6 @@ Riot has since been [renamed to Element](https://element.io/blog/welcome-to-elem
|
||||
- to learn more about Element Web and its configuration, see our dedicated [Configuring Element Web](configuring-playbook-client-element-web.md) documentation page
|
||||
- to learn how to migrate from Riot to Element Web, see [Migrating to Element Web](#migrating-to-element-web) below
|
||||
|
||||
|
||||
## Migrating to Element Web
|
||||
|
||||
### Migrating your custom settings
|
||||
@ -16,7 +15,6 @@ If you have custom `matrix_riot_web_` variables in your `inventory/host_vars/mat
|
||||
|
||||
Some other playbook variables (but not all) with `riot` in their name are also renamed. The playbook checks and warns if you are using the old name for some commonly used ones.
|
||||
|
||||
|
||||
### Domain migration
|
||||
|
||||
We used to set up Riot at the `riot.example.com` domain. The playbook now sets up Element Web at `element.example.com` by default.
|
||||
@ -27,7 +25,6 @@ There are a few options for handling this:
|
||||
|
||||
- (**embracing changes** - using only `element.example.com`) - set up the `element.example.com` DNS record (see [Configuring DNS](configuring-dns.md)). You can drop the `riot.example.com` in this case.
|
||||
|
||||
|
||||
### Re-running the playbook
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
@ -29,7 +29,6 @@ matrix_s3_media_store_custom_endpoint: "https://your-custom-endpoint"
|
||||
|
||||
If you have local media store files and wish to migrate to Backblaze B2 subsequently, follow our [migration guide to Backblaze B2](#migrating-to-backblaze-b2) below instead of applying this configuration as-is.
|
||||
|
||||
|
||||
## Migrating from local filesystem storage to S3
|
||||
|
||||
It's a good idea to [make a complete server backup](faq.md#how-do-i-back-up-the-data-on-my-server) before migrating your local media store to an S3-backed one.
|
||||
@ -85,7 +84,6 @@ After making the backup, follow one of the guides below for a migration path fro
|
||||
|
||||
14. When confident that it all works, get rid of the local media store directory: `rm -rf /matrix/synapse/storage/media-store-local-backup`
|
||||
|
||||
|
||||
### Migrating to Backblaze B2
|
||||
|
||||
1. While all Matrix services are running, run the following command on the server:
|
||||
|
||||
@ -12,7 +12,6 @@ Then, [create the S3 bucket](#bucket-creation-and-security-configuration).
|
||||
|
||||
Finally, [set up S3 storage for Synapse](#setting-up) (with [Goofys](configuring-playbook-s3-goofys.md), [synapse-s3-storage-provider](configuring-playbook-synapse-s3-storage-provider.md), or use s3 datastore with the [matrix-media-repo](https://docs.t2bot.io/matrix-media-repo/configuration/s3-datastore.html)).
|
||||
|
||||
|
||||
## Choosing an Object Storage provider
|
||||
|
||||
You can create [Amazon S3](https://aws.amazon.com/s3/) or another S3-compatible object storage like [Backblaze B2](https://www.backblaze.com/b2/cloud-storage.html), [Storj](https://storj.io), [Wasabi](https://wasabi.com), [Digital Ocean Spaces](https://www.digitalocean.com/products/spaces), etc.
|
||||
@ -32,7 +31,6 @@ Here are some of the important aspects of choosing the right provider:
|
||||
- if a provider's price model is transparent (whether it includes hidden costs like minimum charge, minimum storage term, etc.)
|
||||
- if a provider has free or cheap egress fee (in case you need to get the data out often, for some reason) - likely not too important for the common use-case
|
||||
|
||||
|
||||
## Bucket creation and Security Configuration
|
||||
|
||||
Now that you've [chosen an Object Storage provider](#choosing-an-object-storage-provider), you need to create a storage bucket.
|
||||
@ -66,7 +64,6 @@ You'll need an Amazon S3 bucket and some IAM user credentials (access key + secr
|
||||
|
||||
**Note**: This policy needs to be attached to an IAM user created from the **Security Credentials** menu. This is not a **Bucket Policy**.
|
||||
|
||||
|
||||
## Backblaze B2
|
||||
|
||||
To use [Backblaze B2](https://www.backblaze.com/b2/cloud-storage.html) you first need to sign up.
|
||||
@ -92,14 +89,12 @@ For configuring [Goofys](configuring-playbook-s3-goofys.md) or [s3-synapse-stora
|
||||
|
||||
- **Storage Class** - use `STANDARD`. Backblaze B2 does not have different storage classes, so it doesn't make sense to use any other value.
|
||||
|
||||
|
||||
## Other providers
|
||||
|
||||
For other S3-compatible providers, you may not need to configure security policies, etc. (just like for [Backblaze B2](#backblaze-b2)).
|
||||
|
||||
You most likely just need to create an S3 bucket and get some credentials (access key and secret key) for accessing the bucket in a read/write manner.
|
||||
|
||||
|
||||
## Setting up
|
||||
|
||||
To set up Synapse to store files in S3, follow the instructions for the method of your choice:
|
||||
|
||||
@ -6,7 +6,6 @@ The playbook can install and configure [sliding-sync](https://github.com/matrix-
|
||||
|
||||
Sliding Sync is an implementation of [MSC3575](https://github.com/matrix-org/matrix-spec-proposals/blob/kegan/sync-v3/proposals/3575-sync.md) and a prerequisite for running Element X clients ([Element X iOS](https://github.com/element-hq/element-x-ios) and [Element X Android](https://github.com/element-hq/element-x-android)). See the project's [documentation](https://github.com/matrix-org/sliding-sync) to learn more.
|
||||
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
To enable Sliding Sync proxy, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
|
||||
@ -4,7 +4,6 @@ By default, this playbook retrieves and auto-renews free SSL certificates from [
|
||||
|
||||
This guide is about using the integrated Traefik server and doesn't apply if you're using [your own webserver](configuring-playbook-own-webserver.md).
|
||||
|
||||
|
||||
## Using staging Let's Encrypt certificates instead of real ones
|
||||
|
||||
For testing purposes, you may wish to use staging certificates provide by Let's Encrypt.
|
||||
@ -15,7 +14,6 @@ Add the following configuration to your `inventory/host_vars/matrix.example.com/
|
||||
traefik_config_certificatesResolvers_acme_use_staging: true
|
||||
```
|
||||
|
||||
|
||||
## Disabling SSL termination
|
||||
|
||||
For testing or other purposes, you may wish to install services without SSL termination and have services exposed to `http://` instead of `https://`.
|
||||
@ -26,7 +24,6 @@ Add the following configuration to your `inventory/host_vars/matrix.example.com/
|
||||
traefik_config_entrypoint_web_secure_enabled: false
|
||||
```
|
||||
|
||||
|
||||
## Using self-signed SSL certificates
|
||||
|
||||
If you'd like to use your own SSL certificates, instead of the default (SSL certificates obtained automatically via [ACME](https://en.wikipedia.org/wiki/Automatic_Certificate_Management_Environment) from [Let's Encrypt](https://letsencrypt.org/)):
|
||||
@ -34,7 +31,6 @@ If you'd like to use your own SSL certificates, instead of the default (SSL cert
|
||||
- generate your self-signed certificate files
|
||||
- follow the [Using your own SSL certificates](#using-your-own-ssl-certificates) documentation below
|
||||
|
||||
|
||||
## Using your own SSL certificates
|
||||
|
||||
To use your own SSL certificates with Traefik, you need to:
|
||||
|
||||
@ -6,7 +6,6 @@ synapse-admin is a web UI tool you can use to **administrate users, rooms, media
|
||||
|
||||
💡 **Note**: the latest version of synapse-admin is hosted by [etke.cc](https://etke.cc/) at [admin.etke.cc](https://admin.etke.cc/). If you only need this service occasionally and trust giving your admin credentials to a 3rd party Single Page Application, you can consider using it from there and avoiding the (small) overhead of self-hosting.
|
||||
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
To enable Synapse Admin, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
|
||||
@ -6,7 +6,6 @@ See that project's [documentation](https://github.com/matrix-org/synapse-auto-ac
|
||||
|
||||
**Note**: Synapse [v1.109.0](https://github.com/element-hq/synapse/releases/tag/v1.109.0), the same feature [has been merged](https://github.com/element-hq/synapse/pull/17147) into Synapse (see the [Native alternative](#native-alternative) section below). You'd better use the native feature, instead of the [synapse-auto-invite-accept](https://github.com/matrix-org/synapse-auto-accept-invite) 3rd party module.
|
||||
|
||||
|
||||
## Configuration
|
||||
|
||||
If you decide that you'd like to let this playbook install the [synapse-auto-invite-accept](https://github.com/matrix-org/synapse-auto-accept-invite module for you, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
@ -27,7 +26,6 @@ matrix_synapse_ext_synapse_auto_accept_invite_worker_to_run_on: 'matrix-synapse-
|
||||
|
||||
There might be an [issue with federation](https://github.com/matrix-org/synapse-auto-accept-invite/issues/18).
|
||||
|
||||
|
||||
## Native alternative
|
||||
|
||||
Since Synapse [v1.109.0](https://github.com/element-hq/synapse/releases/tag/v1.109.0), the functionality provided by the [synapse-auto-invite-accept](https://github.com/matrix-org/synapse-auto-accept-invite) 3rd party module [has been made](https://github.com/element-hq/synapse/pull/17147) part of Synapse.
|
||||
|
||||
@ -6,7 +6,6 @@ It's a CLI tool that automatically compresses Synapse's `state_groups` database
|
||||
|
||||
See the project's [documentation](https://github.com/matrix-org/rust-synapse-compress-state/#automated-tool-synapse_auto_compressor) to learn what it does and why it might be useful to you.
|
||||
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
@ -15,7 +14,6 @@ Add the following configuration to your `inventory/host_vars/matrix.example.com/
|
||||
matrix_synapse_auto_compressor_enabled: true
|
||||
```
|
||||
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
@ -4,7 +4,6 @@ If you'd like to store Synapse's content repository (`media_store`) files on Ama
|
||||
|
||||
An alternative (which has worse performance) is to use [Goofys to mount the S3 store to the local filesystem](configuring-playbook-s3-goofys.md).
|
||||
|
||||
|
||||
## How it works?
|
||||
|
||||
Summarized writings here are inspired by [this article](https://quentin.dufour.io/blog/2021-09-14/matrix-synapse-s3-storage/).
|
||||
@ -22,7 +21,6 @@ You can run some scripts to delete the local files once in a while (which we do
|
||||
|
||||
While you will need some local disk space around, it's only to accommodate usage, etc., and won't grow as large as your S3 store.
|
||||
|
||||
|
||||
## Installing
|
||||
|
||||
After [creating the S3 bucket and configuring it](configuring-playbook-s3.md#bucket-creation-and-security-configuration), you can proceed to configure `s3-storage-provider` in your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`):
|
||||
@ -57,7 +55,6 @@ If you have existing files in Synapse's media repository (`/matrix/synapse/media
|
||||
|
||||
Regardless of whether you need to [Migrate your existing files to the S3 store](#migrating-your-existing-media-files-to-the-s3-store) or not, make sure you've familiarized yourself with [How it works?](#how-it-works) above and [Periodically cleaning up the local filesystem](#periodically-cleaning-up-the-local-filesystem) below.
|
||||
|
||||
|
||||
## Migrating your existing media files to the S3 store
|
||||
|
||||
Migrating your existing data can happen in multiple ways:
|
||||
|
||||
@ -16,7 +16,6 @@ Alternatively, **if there is no pre-defined variable** for a Synapse setting you
|
||||
|
||||
- or, if extending the configuration is still not powerful enough for your needs, you can **override the configuration completely** using `matrix_synapse_configuration` (or `matrix_synapse_configuration_yaml`). You can find information about this in [`roles/custom/matrix-synapse/defaults/main.yml`](../roles/custom/matrix-synapse/defaults/main.yml).
|
||||
|
||||
|
||||
## Load balancing with workers
|
||||
|
||||
To have Synapse gracefully handle thousands of users, worker support should be enabled. It factors out some homeserver tasks and spreads the load of incoming client and server-to-server traffic between multiple processes. More information can be found in the [official Synapse workers documentation](https://github.com/element-hq/synapse/blob/master/docs/workers.md) and [Tom Foster](https://github.com/tcpipuk)'s [Synapse homeserver guide](https://tcpipuk.github.io/synapse/index.html).
|
||||
@ -80,12 +79,10 @@ A separate Ansible role (`matrix-synapse-reverse-proxy-companion`) and component
|
||||
|
||||
In case any problems occur, make sure to have a look at the [list of synapse issues about workers](https://github.com/element-hq/synapse/issues?q=workers+in%3Atitle) and your `journalctl --unit 'matrix-*'`.
|
||||
|
||||
|
||||
## Synapse Admin
|
||||
|
||||
Certain Synapse administration tasks (managing users and rooms, etc.) can be performed via a web user-interace, if you install [Synapse Admin](configuring-playbook-synapse-admin.md).
|
||||
|
||||
|
||||
## Synapse + OpenID Connect for Single-Sign-On
|
||||
|
||||
💡 An alternative to setting up OIDC in Synapse is to use [Matrix Authentication Service](./configuring-playbook-matrix-authentication-service.md) (MAS). Newer clients (like Element X) only support SSO-based authentication via MAS and not via the legacy Synapse OIDC setup described below. That said, MAS is still a new experimental service which comes with its own downsides. Consult its documentation to learn if it will be a good fit for your deployment.
|
||||
@ -117,7 +114,6 @@ matrix_synapse_oidc_providers:
|
||||
backchannel_logout_enabled: true # Optional
|
||||
```
|
||||
|
||||
|
||||
## Customizing templates
|
||||
|
||||
[Templates](https://github.com/element-hq/synapse/blob/develop/docs/templates.md) are used by Synapse for showing **certain web pages** handled by the server, as well as for **email notifications**.
|
||||
@ -156,7 +152,6 @@ matrix_synapse_container_image_customizations_templates_git_repository_ssh_priva
|
||||
|
||||
As mentioned in Synapse's Templates documentation, Synapse will fall back to its own templates if a template is not found in that directory. Due to this, it's recommended to only store and maintain template files in your repository if you need to make custom changes. Other files (which you don't need to change), should not be duplicated, so that you don't need to worry about getting out-of-sync with the original Synapse templates.
|
||||
|
||||
|
||||
## Monitoring Synapse Metrics with Prometheus and Grafana
|
||||
|
||||
This playbook allows you to enable Synapse metrics, which can provide insight into the performance and activity of Synapse.
|
||||
|
||||
@ -4,7 +4,6 @@ By default, this playbook configures your Matrix homeserver to not send any tele
|
||||
|
||||
The [matrix.org](https://matrix.org) team would really appreciate it if you could help the project out by reporting usage statistics from your homeserver. Enabling usage statistics helps track the growth of the Matrix community, and helps to make Matrix a success.
|
||||
|
||||
|
||||
## Enabling Telemetry
|
||||
|
||||
If you'd like to **help by enabling submission of general usage statistics** for your homeserver, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
@ -15,7 +14,6 @@ matrix_synapse_report_stats: true # for synapse
|
||||
matrix_dendrite_report_stats: true # for dendrite
|
||||
```
|
||||
|
||||
|
||||
## Usage statistics being submitted
|
||||
|
||||
When enabled, your homeserver will regularly upload a few dozen statistics about your server. This data includes your homeserver's domain, the total number of users, the number of active users, the total number of rooms, and the number of messages sent per day on your homeserver.
|
||||
|
||||
@ -4,7 +4,6 @@ By default, this playbook installs and manages a [Traefik](https://doc.traefik.i
|
||||
|
||||
This Ansible role support various configuration options. Feel free to consult its `default/main.yml` variables file.
|
||||
|
||||
|
||||
## Adjusting SSL certificate retrieval
|
||||
|
||||
See the dedicated [Adjusting SSL certificate retrieval](configuring-playbook-ssl-certificates.md) documentation page.
|
||||
@ -89,7 +88,6 @@ traefik_configuration_extension_yaml: |
|
||||
insecureSkipVerify: true
|
||||
```
|
||||
|
||||
|
||||
Next, you have to add a new dynamic configuration file for Traefik that contains the actual information of the server using the `aux_file_definitions` variable. In this example, we will terminate SSL at the Traefik instance and connect to the other server via HTTPS. Traefik will now take care of managing the certificates.
|
||||
|
||||
```yaml
|
||||
@ -138,7 +136,6 @@ With these changes, all TCP traffic will be reverse-proxied to the target system
|
||||
|
||||
**WARNING**: This configuration might lead to problems or need additional steps when a [certbot](https://certbot.eff.org/) behind Traefik also tries to manage [Let's Encrypt](https://letsencrypt.org/) certificates, as Traefik captures all traffic to ```PathPrefix(`/.well-known/acme-challenge/`)```.
|
||||
|
||||
|
||||
## Traefik behind a `proxy_protocol` reverse-proxy
|
||||
|
||||
If you run a reverse-proxy which speaks `proxy_protocol`, add the following to your configuration file:
|
||||
|
||||
@ -4,7 +4,6 @@ The playbook installs a [Coturn](https://github.com/coturn/coturn) TURN server b
|
||||
|
||||
By default, the Synapse chat server is configured, so that it points to the Coturn TURN server installed by the playbook.
|
||||
|
||||
|
||||
## Disabling Coturn
|
||||
|
||||
If, for some reason, you'd like to prevent the playbook from installing Coturn, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
@ -48,7 +47,6 @@ Regardless of the selected authentication method, the playbook generates secrets
|
||||
|
||||
If you're using [Jitsi](./configuring-playbook-jitsi.md), note that switching to `lt-cred-mech` will remove the integration between Jitsi and your own Coturn server, because Jitsi only seems to support the `auth-secret` authentication method.
|
||||
|
||||
|
||||
## Using your own external Coturn server
|
||||
|
||||
If you'd like to use another TURN server (be it Coturn or some other one), you can configure the playbook like this:
|
||||
|
||||
@ -68,6 +68,7 @@ matrix_user_verification_service_uvs_auth_token: "TOKEN"
|
||||
In case Jitsi is also managed by this playbook and 'matrix' authentication in Jitsi is enabled, this collection will automatically configure Jitsi to use the configured auth token.
|
||||
|
||||
### (Optional) Disable Auth
|
||||
|
||||
Authorization is enabled by default. To disable set
|
||||
|
||||
```yaml
|
||||
@ -108,6 +109,7 @@ The configuration variable `UVS_LOG_LEVEL` can be set to:
|
||||
- debug
|
||||
|
||||
## TLS Certificate Checking
|
||||
|
||||
If the Matrix Homeserver does not provide a valid TLS certificate, UVS will fail with the following error message:
|
||||
|
||||
> message: 'No response received: [object Object]',
|
||||
|
||||
@ -24,7 +24,6 @@ For a more custom setup, see the [Other configuration options](#other-configurat
|
||||
|
||||
[▶️](installing.md) When you're done with all the configuration you'd like to do, continue with [Installing](installing.md).
|
||||
|
||||
|
||||
## Other configuration options
|
||||
|
||||
### Core service adjustments
|
||||
@ -166,7 +165,6 @@ Bridges can be used to connect your Matrix installation with third-party communi
|
||||
|
||||
- [Setting up WeChat bridging](configuring-playbook-bridge-wechat.md)
|
||||
|
||||
|
||||
### Bots
|
||||
|
||||
Bots provide various additional functionality to your installation.
|
||||
|
||||
@ -177,7 +177,6 @@ Make sure to:
|
||||
- **replace `example.com`** in the server configuration with your actual domain name
|
||||
- and: to **do this for the HTTPS-enabled server block**, as that's where Matrix expects the file to be
|
||||
|
||||
|
||||
## Confirming it works
|
||||
|
||||
No matter which method you've used to set up the well-known files, if you've done it correctly you should be able to see a JSON file at these URLs:
|
||||
|
||||
@ -4,7 +4,6 @@ This page summarizes the container ([Docker](https://www.docker.com/)) images us
|
||||
|
||||
We try to stick to official images (provided by their respective projects) as much as possible.
|
||||
|
||||
|
||||
## Homeserver
|
||||
|
||||
| Service | Container image | Default? | Description |
|
||||
|
||||
@ -229,7 +229,6 @@ Besides the regular Matrix stuff, we also support things like video-conferencing
|
||||
|
||||
If your distro runs within an [LXC container](https://linuxcontainers.org/), you may hit [this issue](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/703). It can be worked around, if absolutely necessary, but we suggest that you avoid running from within an LXC container.
|
||||
|
||||
|
||||
## Configuration
|
||||
|
||||
### Why install my server at matrix.example.com and not at the base domain?
|
||||
@ -372,7 +371,6 @@ Check each role's `roles/*/*/defaults/main.yml` for the corresponding variable a
|
||||
|
||||
**Note**: some of the roles (`roles/galaxy/*`) live in separate repositories and are only installed after your run `just roles` (or `make roles`) or `just update` (which automatically does `git pull` and `just roles`).
|
||||
|
||||
|
||||
## Installation
|
||||
|
||||
### How do I run the installation?
|
||||
@ -405,7 +403,6 @@ It can perform a local connection instead. Just set `ansible_connection=local` a
|
||||
|
||||
If you're running Ansible from within a container (one of the possibilities we list on our [dedicated Ansible documentation page](ansible.md)), then using `ansible_connection=local` is not possible.
|
||||
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### I get "Error response from daemon: configured logging driver does not support reading" when I do `docker logs matrix-synapse`.
|
||||
@ -445,7 +442,6 @@ RateLimitBurst=0
|
||||
Storage=persistent
|
||||
```
|
||||
|
||||
|
||||
## Maintenance
|
||||
|
||||
### Do I need to do anything to keep my Matrix server updated?
|
||||
|
||||
@ -12,7 +12,6 @@ You can retrieve the playbook's source code by:
|
||||
|
||||
- [Downloading the playbook as a ZIP archive](#downloading-the-playbook-as-a-zip-archive) (not recommended)
|
||||
|
||||
|
||||
## Using git to get the playbook
|
||||
|
||||
We recommend using the [git](https://git-scm.com/) tool to get the playbook's source code, because it lets you easily keep up to date in the future when [Maintaining services](maintenance-upgrading-services.md).
|
||||
@ -25,7 +24,6 @@ git clone https://github.com/spantaleev/matrix-docker-ansible-deploy.git
|
||||
|
||||
This will create a new `matrix-docker-ansible-deploy` directory. You're supposed to execute all other installation commands inside that directory.
|
||||
|
||||
|
||||
## Downloading the playbook as a ZIP archive
|
||||
|
||||
Alternatively, you can download the playbook as a ZIP archive. This is not recommended, as it's not easy to keep up to date with future updates. We suggest you [use git](#using-git-to-get-the-playbook) instead.
|
||||
@ -34,7 +32,6 @@ The latest version is always at the following URL: https://github.com/spantaleev
|
||||
|
||||
You can extract this archive anywhere. You'll get a directory called `matrix-docker-ansible-deploy-master`. You're supposed to execute all other installation commands inside that directory.
|
||||
|
||||
|
||||
---------------------------------------------
|
||||
|
||||
[▶️](configuring-playbook.md) No matter which method you've used to download the playbook, you can proceed by [Configuring the playbook](configuring-playbook.md).
|
||||
|
||||
@ -33,7 +33,6 @@ Server Delegation by means of a `/.well-known/matrix/server` file is the most st
|
||||
|
||||
Otherwise, you can decide to go against the default for this playbook, and instead set up [Server Delegation via a DNS SRV record (advanced)](#server-delegation-via-a-dns-srv-record-advanced) (much more complicated).
|
||||
|
||||
|
||||
## Server Delegation via a DNS SRV record (advanced)
|
||||
|
||||
**Note**: doing Server Delegation via a DNS SRV record is a more **advanced** way to do it and is not the default for this playbook. This is usually **much more complicated** to set up, so **we don't recommend it**. If you're not an experienced sysadmin, you'd better stay away from this.
|
||||
@ -60,7 +59,6 @@ If `example.com` and `matrix.example.com` are hosted on the same machine, you ca
|
||||
|
||||
If `example.com` and `matrix.example.com` are not hosted on the same machine, you can copy over the certificate files manually. Don't forget that they may get renewed once in a while, so you may also have to transfer them periodically. How often you do that is up to you, as long as the certificate files don't expire.
|
||||
|
||||
|
||||
### Serving the Federation API with your certificates
|
||||
|
||||
Regardless of which method for obtaining certificates you've used, once you've managed to get certificates for your base domain onto the `matrix.example.com` machine you can put them to use.
|
||||
|
||||
@ -3,7 +3,6 @@
|
||||
Run this if you'd like to import your database from a previous installation.
|
||||
(don't forget to import your Synapse `media_store` files as well - see [the importing-synape-media-store guide](importing-synapse-media-store.md)).
|
||||
|
||||
|
||||
## Prerequisites
|
||||
|
||||
For this to work, **the database name in Postgres must match** what this playbook uses. This playbook uses a Postgres database name of `synapse` by default (controlled by the `matrix_synapse_database_database` variable). If your database name differs, be sure to change `matrix_synapse_database_database` to your desired name and to re-run the playbook before proceeding.
|
||||
@ -14,7 +13,6 @@ The migration might be a good moment, to "reset" a not properly working bridge.
|
||||
|
||||
Before doing the actual import, **you need to upload your Postgres dump file to the server** (any path is okay).
|
||||
|
||||
|
||||
## Importing
|
||||
|
||||
To import, run this command (make sure to replace `SERVER_PATH_TO_POSTGRES_DUMP_FILE` with a file path on your server):
|
||||
@ -34,6 +32,7 @@ just run-tags import-postgres \
|
||||
## Troubleshooting
|
||||
|
||||
### Table Ownership
|
||||
|
||||
A table ownership issue can occur if you are importing from a Synapse installation which was both:
|
||||
|
||||
- migrated from SQLite to Postgres, and
|
||||
@ -86,6 +85,7 @@ In this case you can use the command suggested in the import task to clear the d
|
||||
Now on your local machine run `just run-tags setup-postgres` to prepare the database roles etc.
|
||||
|
||||
If not, you probably get this error. `synapse` is the correct table owner, but the role is missing in database.
|
||||
|
||||
```
|
||||
"ERROR: role synapse does not exist"
|
||||
```
|
||||
|
||||
@ -2,7 +2,6 @@
|
||||
|
||||
Run this if you'd like to import your `media_store` files from a previous installation of Synapse.
|
||||
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before doing the actual data restore, **you need to upload your media store directory to the server** (any path is okay).
|
||||
@ -13,7 +12,6 @@ As an alternative, you can perform a manual restore using the [AWS CLI tool](htt
|
||||
|
||||
**Note for Mac users**: Due to case-sensitivity issues on certain Mac filesystems (HFS or HFS+), filename corruption may occur if you copy a `media_store` directory to your Mac. If you're transferring a `media_store` directory between 2 servers, make sure you do it directly (from server to server with a tool such as [rsync](https://rsync.samba.org/)), and not by downloading the files to your Mac.
|
||||
|
||||
|
||||
## Importing
|
||||
|
||||
Run this command (make sure to replace `<server-path-to-media_store>` with a path on your server):
|
||||
|
||||
@ -6,7 +6,6 @@ While this playbook only supports running Synapse in combination with PostgreSQL
|
||||
|
||||
If you have such a Synapse setup and wish to migrate it to one managed by the playbook (and over to PostgreSQL), this documentation page is for you.
|
||||
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before doing the actual import:
|
||||
|
||||
@ -3,6 +3,7 @@
|
||||
## How to see the current status of your services
|
||||
|
||||
You can check the status of your services by using `systemctl status`. Example:
|
||||
|
||||
```sh
|
||||
sudo systemctl status matrix-synapse
|
||||
|
||||
@ -21,7 +22,6 @@ To view systemd-journald logs using [journalctl](https://man.archlinux.org/man/j
|
||||
sudo journalctl -fu matrix-synapse
|
||||
```
|
||||
|
||||
|
||||
## Increasing Synapse logging
|
||||
|
||||
Because the [Synapse](https://github.com/element-hq/synapse) Matrix server is originally very chatty when it comes to logging, we intentionally reduce its [logging level](https://docs.python.org/3/library/logging.html#logging-levels) from `INFO` to `WARNING`.
|
||||
|
||||
@ -30,7 +30,6 @@ You can then proceed to write queries. Example: `SELECT COUNT(*) FROM users;`
|
||||
|
||||
**Be careful**. Modifying the database directly (especially as services are running) is dangerous and may lead to irreversible database corruption. When in doubt, consider [making a backup](#backing-up-postgresql).
|
||||
|
||||
|
||||
## Vacuuming PostgreSQL
|
||||
|
||||
Deleting lots data from Postgres does not make it release disk space, until you perform a [`VACUUM` operation](https://www.postgresql.org/docs/current/sql-vacuum.html).
|
||||
@ -50,7 +49,6 @@ Example playbook invocations:
|
||||
- `just run-tags run-postgres-vacuum`: runs the default `vacuum-complete` preset and restarts all services
|
||||
- `just run-tags run-postgres-vacuum -e postgres_vacuum_preset=analyze`: runs the `analyze` preset with all services remaining operational at all times
|
||||
|
||||
|
||||
## Backing up PostgreSQL
|
||||
|
||||
To automatically make Postgres database backups on a fixed schedule, see [Setting up postgres backup](configuring-playbook-postgres-backup.md).
|
||||
@ -70,7 +68,6 @@ If you are using an [external Postgres server](configuring-playbook-external-pos
|
||||
|
||||
Restoring a backup made this way can be done by [importing it](importing-postgres.md).
|
||||
|
||||
|
||||
## Upgrading PostgreSQL
|
||||
|
||||
Unless you are using an [external Postgres server](configuring-playbook-external-postgres.md), this playbook initially installs Postgres for you.
|
||||
@ -91,12 +88,10 @@ The auto-upgrade-backup directory stays around forever, until you **manually dec
|
||||
|
||||
As part of the upgrade, the database is dumped to `/tmp`, an upgraded and empty Postgres server is started, and then the dump is restored into the new server. To use a different directory for the dump, pass some extra flags to the command above, like this: `--extra-vars="postgres_dump_dir=/directory/to/dump/here"`
|
||||
|
||||
To save disk space in `/tmp`, the dump file is gzipped on the fly at the expense of CPU usage.
|
||||
If you have plenty of space in `/tmp` and would rather avoid gzipping, you can explicitly pass a dump filename which doesn't end in `.gz`. Example: `--extra-vars="postgres_dump_name=matrix-postgres-dump.sql"`
|
||||
To save disk space in `/tmp`, the dump file is gzipped on the fly at the expense of CPU usage. If you have plenty of space in `/tmp` and would rather avoid gzipping, you can explicitly pass a dump filename which doesn't end in `.gz`. Example: `--extra-vars="postgres_dump_name=matrix-postgres-dump.sql"`
|
||||
|
||||
**All databases, roles, etc. on the Postgres server are migrated**.
|
||||
|
||||
|
||||
## Tuning PostgreSQL
|
||||
|
||||
PostgreSQL can be [tuned](https://wiki.postgresql.org/wiki/Tuning_Your_PostgreSQL_Server) to make it run faster. This is done by passing extra arguments to the Postgres process.
|
||||
|
||||
@ -24,7 +24,6 @@ Follow the [Purge History API](https://github.com/element-hq/synapse/blob/master
|
||||
|
||||
After deleting data, you may wish to run a [`FULL` Postgres `VACUUM`](./maintenance-postgres.md#vacuuming-postgresql).
|
||||
|
||||
|
||||
## Compressing state with rust-synapse-compress-state
|
||||
|
||||
[rust-synapse-compress-state](https://github.com/matrix-org/rust-synapse-compress-state) can be used to optimize some `_state` tables used by Synapse. If your server participates in large rooms this is the most effective way to reduce the size of your database.
|
||||
@ -45,7 +44,6 @@ By default, all rooms with more than `100000` state group rows will be compresse
|
||||
|
||||
After state compression, you may wish to run a [`FULL` Postgres `VACUUM`](./maintenance-postgres.md#vacuuming-postgresql).
|
||||
|
||||
|
||||
## Browse and manipulate the database
|
||||
|
||||
When the [Synapse Admin API](https://github.com/element-hq/synapse/tree/master/docs/admin_api) and the other tools do not provide a more convenient way, having a look at synapse's postgresql database can satisfy a lot of admins' needs.
|
||||
|
||||
@ -20,7 +20,6 @@ Below, we describe 2 ways to generate an access token for a user - using [Elemen
|
||||
|
||||
|
||||
|
||||
|
||||
## Obtain an access token via curl
|
||||
|
||||
You can use the following command to get an access token for your user directly from the [Matrix Client-Server API](https://www.matrix.org/docs/guides/client-server-api#login):
|
||||
|
||||
@ -11,7 +11,6 @@ Table of contents:
|
||||
- [Enabling public user registration](#enabling-public-user-registration)
|
||||
- [Adding/Removing Administrator privileges to an existing user](#addingremoving-administrator-privileges-to-an-existing-user)
|
||||
|
||||
|
||||
## Registering users manually
|
||||
|
||||
**Notes**:
|
||||
@ -83,19 +82,16 @@ This `register-user` script actually invokes the `mas-cli manage register-user`
|
||||
|
||||
⚠️ **Warning**: Matrix Authentication Service [still insists](https://github.com/element-hq/matrix-authentication-service/issues/1505) on having a verified email address for each user. Upon a user's first login, they will be asked to confirm their email address. This requires that email sending is [configured](./configuring-playbook-email.md). You can also consult the [Working around email deliverability issues](./configuring-playbook-matrix-authentication-service.md#working-around-email-deliverability-issues) section for more information.
|
||||
|
||||
|
||||
## Managing users via a Web UI
|
||||
|
||||
To manage users more easily (via a web user-interace), you can install [Synapse Admin](configuring-playbook-synapse-admin.md).
|
||||
|
||||
⚠️ **Warning**: If you're using [Matrix Authentication Service](configuring-playbook-matrix-authentication-service.md), note that user management via synapse-admin is not fully working yet. See the [Expectations](configuring-playbook-matrix-authentication-service.md#expectations) section for more information.
|
||||
|
||||
|
||||
## Letting certain users register on your private server
|
||||
|
||||
If you'd rather **keep your server private** (public registration closed, as is the default), and **let certain people create accounts by themselves** (instead of creating user accounts manually like this), consider installing and making use of [matrix-registration](configuring-playbook-matrix-registration.md).
|
||||
|
||||
|
||||
## Enabling public user registration
|
||||
|
||||
To **open up user registration publicly** (usually **not recommended**), add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
|
||||
@ -6,17 +6,14 @@
|
||||
|
||||
- If you have some trouble with your installation, you can just [re-run the playbook](installing.md) and it will try to set things up again. **Uninstalling and then installing anew rarely solves anything**.
|
||||
|
||||
|
||||
-----------------
|
||||
|
||||
|
||||
## Uninstalling using a script
|
||||
|
||||
Installing places a `/matrix/bin/remove-all` script on the server.
|
||||
|
||||
You can run it to to have it uninstall things for you automatically (see below). **Use with caution!**
|
||||
|
||||
|
||||
## Uninstalling manually
|
||||
|
||||
If you prefer to uninstall manually, run these commands (most are meant to be executed on the Matrix server itself):
|
||||
@ -32,5 +29,3 @@ If you prefer to uninstall manually, run these commands (most are meant to be ex
|
||||
- uninstall Docker itself, if necessary
|
||||
|
||||
- delete the `/matrix` directory (`rm -rf /matrix`)
|
||||
|
||||
|
||||
|
||||
@ -14,7 +14,6 @@ ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=USERNAME_HE
|
||||
|
||||
**You can then log in with that user** via Element Web that this playbook has created for you at a URL like this: `https://element.example.com/`.
|
||||
|
||||
|
||||
## Option 2 (if you are using an external Postgres server):
|
||||
|
||||
You can manually generate the password hash by using the command-line after **SSH**-ing to your server (requires that [all services have been started](installing.md#finalize-the-installation):
|
||||
@ -31,7 +30,6 @@ UPDATE users SET password_hash = '<password-hash>' WHERE name = '@someone:exampl
|
||||
|
||||
where `<password-hash>` is the hash returned by the docker command above.
|
||||
|
||||
|
||||
## Option 3:
|
||||
|
||||
Use the Synapse User Admin API as described here: https://github.com/element-hq/synapse/blob/master/docs/admin_api/user_admin_api.rst#reset-password
|
||||
@ -41,7 +39,9 @@ This requires an [access token](obtaining-access-tokens.md) from a server admin
|
||||
If you didn't make your account a server admin when you created it, you can learn how to switch it now by reading about it in [Adding/Removing Administrator privileges to an existing user in Synapse](registering-users.md#addingremoving-administrator-privileges-to-an-existing-user-in-synapse).
|
||||
|
||||
### Example:
|
||||
|
||||
To set @user:example.com's password to `correct_horse_battery_staple` you could use this curl command:
|
||||
|
||||
```sh
|
||||
curl -XPOST -d '{ "new_password": "correct_horse_battery_staple" }' "https://matrix.example.com/_matrix/client/r0/admin/reset_password/@user:example.com?access_token=MDA...this_is_my_access_token
|
||||
```
|
||||
|
||||
@ -4,7 +4,6 @@ This directory contains a sample config that shows you how to front the integrat
|
||||
|
||||
**Note**: if you're running Caddy on the host itself (not in a container), refer to the [caddy2](../caddy2/README.md) example instead.
|
||||
|
||||
|
||||
## Prerequisite configuration
|
||||
|
||||
To get started, first follow the [front the integrated reverse-proxy webserver with another reverse-proxy](../../../docs/configuring-playbook-own-webserver.md#fronting-the-integrated-reverse-proxy-webserver-with-another-reverse-proxy) instructions and update your playbook's configuration (`inventory/host_vars/matrix.example.com/vars.yml`).
|
||||
|
||||
@ -2,12 +2,10 @@
|
||||
|
||||
This directory contains a sample config that shows you how to front the integrated [Traefik](https://traefik.io/) reverse-proxy webserver with your own [Caddy](https://caddyserver.com/) reverse-proxy.
|
||||
|
||||
|
||||
## Prerequisite configuration
|
||||
|
||||
To get started, first follow the [front the integrated reverse-proxy webserver with another reverse-proxy](../../../docs/configuring-playbook-own-webserver.md#fronting-the-integrated-reverse-proxy-webserver-with-another-reverse-proxy) instructions and update your playbook's configuration (`inventory/host_vars/matrix.example.com/vars.yml`).
|
||||
|
||||
|
||||
## Using the Caddyfile
|
||||
|
||||
You can either just use the [Caddyfile](Caddyfile) directly or append its content to your own Caddyfile.
|
||||
|
||||
@ -4,14 +4,12 @@ Similar to standard nginx, [Nginx Proxy Manager](https://nginxproxymanager.com/)
|
||||
|
||||
This page summarizes how to use Nginx Proxy Manager (NPM) to front the integrated [Traefik](https://traefik.io/) reverse-proxy webserver.
|
||||
|
||||
|
||||
## Prerequisite configuration
|
||||
|
||||
To get started, first follow the [front the integrated reverse-proxy webserver with another reverse-proxy](../../../docs/configuring-playbook-own-webserver.md#fronting-the-integrated-reverse-proxy-webserver-with-another-reverse-proxy) instructions and update your playbook's configuration (`inventory/host_vars/matrix.example.com/vars.yml`).
|
||||
|
||||
If Matrix federation is enabled, then you will need to make changes to [NPM's Docker configuration](https://nginxproxymanager.com/guide/#quick-setup). By default NPM already exposes ports `80` and `443`, but you would also need to **additionally expose the Matrix Federation port** (as it appears on the public side): `8448`.
|
||||
|
||||
|
||||
## Using Nginx Proxy Manager
|
||||
|
||||
You'll need to create two proxy hosts in NPM for Matrix web and federation traffic.
|
||||
|
||||
@ -2,12 +2,10 @@
|
||||
|
||||
This directory contains a sample config that shows you how to use the [nginx](https://nginx.org/) webserver to front the integrated [Traefik](https://traefik.io/) reverse-proxy webserver with another reverse-proxy.
|
||||
|
||||
|
||||
## Prerequisite configuration
|
||||
|
||||
To get started, first follow the [front the integrated reverse-proxy webserver with another reverse-proxy](../../../docs/configuring-playbook-own-webserver.md#fronting-the-integrated-reverse-proxy-webserver-with-another-reverse-proxy) instructions and update your playbook's configuration (`inventory/host_vars/matrix.example.com/vars.yml`).
|
||||
|
||||
|
||||
## Using the nginx configuration
|
||||
|
||||
Copy the [matrix.conf](matrix.conf) file to your nginx server's filesystem, modify it to your needs and include it in your nginx configuration (e.g. `include /path/to/matrix.conf;`).
|
||||
|
||||
Loading…
Reference in New Issue
Block a user