From ecd4fc028d071116423bdc104755027d3018608c Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Mon, 28 Oct 2024 23:27:42 +0900 Subject: [PATCH] Recategorize Postmoogle (#3696) * Update configuring-playbook.md: move a link for docs/configuring-playbook-bot-postmoogle.md to Bots section The document (on 9c2a8addee93910cb9079f856bc3fb3932592c91; initial commit to add Postmoogle) says: > Postmoogle is a bot/bridge you can use to forward emails to Matrix rooms Therefore it is not really incorrect to categorize Postmoogle as bridge document-wise, but since the list on README.md categorizes it as a bot, and based on the file name of the documentation, this commit moves the link for Postmoogle to the Bots section. Signed-off-by: Suguru Hirahara * Revert "Update configuring-playbook.md: move a link for docs/configuring-playbook-bot-postmoogle.md to Bots section" This reverts commit 1e2e903cb955fcf5033788c508816293b837e9f5. * Change the file name of Postmoogle documentation to make it clear that Postmoogle is a bridge Signed-off-by: Suguru Hirahara * Update documentation for Postmoogle related to a bridge/bot status Signed-off-by: Suguru Hirahara --------- Signed-off-by: Suguru Hirahara Co-authored-by: Suguru Hirahara --- CHANGELOG.md | 6 +-- README.md | 2 +- docs/configuring-dns.md | 42 +++++++++---------- ...configuring-playbook-bridge-postmoogle.md} | 10 ++--- docs/configuring-playbook-email2matrix.md | 2 +- ...-playbook-matrix-authentication-service.md | 2 +- docs/configuring-playbook.md | 2 +- .../matrix-bot-postmoogle/defaults/main.yml | 2 +- 8 files changed, 34 insertions(+), 34 deletions(-) rename docs/{configuring-playbook-bot-postmoogle.md => configuring-playbook-bridge-postmoogle.md} (77%) diff --git a/CHANGELOG.md b/CHANGELOG.md index 38b5d579b..c56c2f4bb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1110,7 +1110,7 @@ Switching to Traefik will obtain new SSL certificates from Let's Encrypt (stored Treafik directly reverse-proxies to **some** services right now, but for most other services it goes through `matrix-nginx-proxy` (e.g. Traefik -> `matrix-nginx-proxy` -> [Ntfy](docs/configuring-playbook-ntfy.md)). So, even if you opt into Traefik, you'll still see `matrix-nginx-proxy` being installed in local-only mode. This will improve with time. -Some services (like [Coturn](docs/configuring-playbook-turn.md) and [Postmoogle](docs/configuring-playbook-bot-postmoogle.md)) cannot be reverse-proxied to directly from Traefik, so they require direct access to SSL certificate files extracted out of Traefik. The playbook does this automatically thanks to a new [com.devture.ansible.role.traefik_certs_dumper](https://github.com/devture/com.devture.ansible.role.traefik_certs_dumper) role utilizing the [traefik-certs-dumper](https://github.com/ldez/traefik-certs-dumper) tool. +Some services (like [Coturn](docs/configuring-playbook-turn.md) and [Postmoogle](docs/configuring-playbook-bridge-postmoogle.md)) cannot be reverse-proxied to directly from Traefik, so they require direct access to SSL certificate files extracted out of Traefik. The playbook does this automatically thanks to a new [com.devture.ansible.role.traefik_certs_dumper](https://github.com/devture/com.devture.ansible.role.traefik_certs_dumper) role utilizing the [traefik-certs-dumper](https://github.com/ldez/traefik-certs-dumper) tool. 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. @@ -1571,9 +1571,9 @@ See our [Setting up Cactus Comments](docs/configuring-playbook-cactus-comments.m ## Postmoogle email bridge support -Thanks to [Aine](https://gitlab.com/etke.cc) of [etke.cc](https://etke.cc/), the playbook can now set up the new [Postmoogle](https://github.com/etkecc/postmoogle) email bridge/bot. Postmoogle is like the [email2matrix bridge](https://github.com/devture/email2matrix) (also [already supported by the playbook](docs/configuring-playbook-email2matrix.md)), but more capable and with the intention to soon support *sending* emails, not just receiving. +Thanks to [Aine](https://gitlab.com/etke.cc) of [etke.cc](https://etke.cc/), the playbook can now set up the new [Postmoogle](https://github.com/etkecc/postmoogle) email bridge. Postmoogle is like the [email2matrix bridge](https://github.com/devture/email2matrix) (also [already supported by the playbook](docs/configuring-playbook-email2matrix.md)), but more capable and with the intention to soon support *sending* emails, not just receiving. -See our [Setting up Postmoogle email bridging](docs/configuring-playbook-bot-postmoogle.md) documentation to get started. +See our [Setting up Postmoogle email bridging](docs/configuring-playbook-bridge-postmoogle.md) documentation to get started. # 2022-08-10 diff --git a/README.md b/README.md index a648a9634..ef62d6e89 100644 --- a/README.md +++ b/README.md @@ -125,6 +125,7 @@ Bridges can be used to connect your Matrix installation with third-party communi | [mx-puppet-groupme](https://gitlab.com/xangelix-pub/matrix/mx-puppet-groupme) | x | Bridge to [GroupMe](https://groupme.com/) | [Link](docs/configuring-playbook-bridge-mx-puppet-groupme.md) | | [mx-puppet-steam](https://github.com/icewind1991/mx-puppet-steam) | x | Bridge to [Steam](https://steamapp.com/) | [Link](docs/configuring-playbook-bridge-mx-puppet-steam.md) | | [Email2Matrix](https://github.com/devture/email2matrix) | x | Bridge for relaying emails to Matrix rooms | [Link](docs/configuring-playbook-email2matrix.md) | +| [Postmoogle](https://github.com/etkecc/postmoogle) | x | Email to Matrix bridge | [Link](docs/configuring-playbook-bridge-postmoogle.md) | ### Bots @@ -138,7 +139,6 @@ Bots provide various additional functionality to your installation. | [matrix-registration-bot](https://github.com/moan0s/matrix-registration-bot) | x | Bot for invitations by creating and managing registration tokens | [Link](docs/configuring-playbook-bot-matrix-registration-bot.md) | | [maubot](https://github.com/maubot/maubot) | x | A plugin-based Matrix bot system | [Link](docs/configuring-playbook-bot-maubot.md) | | [Honoroit](https://github.com/etkecc/honoroit) | x | A helpdesk bot | [Link](docs/configuring-playbook-bot-honoroit.md) | -| [Postmoogle](https://github.com/etkecc/postmoogle) | x | Email to Matrix bot | [Link](docs/configuring-playbook-bot-postmoogle.md) | | [Go-NEB](https://github.com/matrix-org/go-neb) | x | A multi functional bot written in Go | [Link](docs/configuring-playbook-bot-go-neb.md) | | [Mjolnir](https://github.com/matrix-org/mjolnir) | x | A moderation tool for Matrix | [Link](docs/configuring-playbook-bot-mjolnir.md) | | [Draupnir](https://github.com/the-draupnir-project/Draupnir) | x | A moderation tool for Matrix (Fork of Mjolnir) | [Link](docs/configuring-playbook-bot-draupnir.md) | diff --git a/docs/configuring-dns.md b/docs/configuring-dns.md index 58482f5a6..a9a3f3244 100644 --- a/docs/configuring-dns.md +++ b/docs/configuring-dns.md @@ -28,26 +28,26 @@ When you're done configuring DNS, proceed to [Configuring the playbook](configur ## DNS settings for optional services/features -| Used by component | Type | Host | Priority | Weight | Port | Target | -| ----------------------------------------------------------------------------------------------------------------------- | ----- | ------------------------------ | -------- | ------ | ---- | --------------------------- | -| [ma1sd](configuring-playbook-ma1sd.md) identity server | SRV | `_matrix-identity._tcp` | 10 | 0 | 443 | `matrix.example.com` | -| [Dimension](configuring-playbook-dimension.md) integration server | CNAME | `dimension` | - | - | - | `matrix.example.com` | -| [Jitsi](configuring-playbook-jitsi.md) video-conferencing platform | CNAME | `jitsi` | - | - | - | `matrix.example.com` | -| [Prometheus/Grafana](configuring-playbook-prometheus-grafana.md) monitoring system | CNAME | `stats` | - | - | - | `matrix.example.com` | -| [Go-NEB](configuring-playbook-bot-go-neb.md) bot | CNAME | `goneb` | - | - | - | `matrix.example.com` | -| [Sygnal](configuring-playbook-sygnal.md) push notification gateway | CNAME | `sygnal` | - | - | - | `matrix.example.com` | -| [ntfy](configuring-playbook-ntfy.md) push notifications server | CNAME | `ntfy` | - | - | - | `matrix.example.com` | -| [Etherpad](configuring-playbook-etherpad.md) collaborative text editor | CNAME | `etherpad` | - | - | - | `matrix.example.com` | -| [Hydrogen](configuring-playbook-client-hydrogen.md) web client | CNAME | `hydrogen` | - | - | - | `matrix.example.com` | -| [Cinny](configuring-playbook-client-cinny.md) web client | CNAME | `cinny` | - | - | - | `matrix.example.com` | -| [SchildiChat](configuring-playbook-client-schildichat.md) web client | CNAME | `schildichat` | - | - | - | `matrix.example.com` | -| [wsproxy](configuring-playbook-bridge-mautrix-wsproxy.md) sms bridge | CNAME | `wsproxy` | - | - | - | `matrix.example.com` | -| [Buscarron](configuring-playbook-bot-buscarron.md) helpdesk bot | CNAME | `buscarron` | - | - | - | `matrix.example.com` | -| [rageshake](docs/configuring-playbook-rageshake.md) bug report server | CNAME | `rageshake` | - | - | - | `matrix.example.com` | -| [Postmoogle](configuring-playbook-bot-postmoogle.md)/[Email2Matrix](configuring-playbook-email2matrix.md) email bridges | MX | `matrix` | 10 | 0 | - | `matrix.example.com` | -| [Postmoogle](configuring-playbook-bot-postmoogle.md) email bridge | TXT | `matrix` | - | - | - | `v=spf1 ip4: -all` | -| [Postmoogle](configuring-playbook-bot-postmoogle.md) email bridge | TXT | `_dmarc.matrix` | - | - | - | `v=DMARC1; p=quarantine;` | -| [Postmoogle](configuring-playbook-bot-postmoogle.md) email bridge | TXT | `postmoogle._domainkey.matrix` | - | - | - | get it from `!pm dkim` | +| Used by component | Type | Host | Priority | Weight | Port | Target | +| -------------------------------------------------------------------------------------------------------------------------- | ----- | ------------------------------ | -------- | ------ | ---- | --------------------------- | +| [ma1sd](configuring-playbook-ma1sd.md) identity server | SRV | `_matrix-identity._tcp` | 10 | 0 | 443 | `matrix.example.com` | +| [Dimension](configuring-playbook-dimension.md) integration server | CNAME | `dimension` | - | - | - | `matrix.example.com` | +| [Jitsi](configuring-playbook-jitsi.md) video-conferencing platform | CNAME | `jitsi` | - | - | - | `matrix.example.com` | +| [Prometheus/Grafana](configuring-playbook-prometheus-grafana.md) monitoring system | CNAME | `stats` | - | - | - | `matrix.example.com` | +| [Go-NEB](configuring-playbook-bot-go-neb.md) bot | CNAME | `goneb` | - | - | - | `matrix.example.com` | +| [Sygnal](configuring-playbook-sygnal.md) push notification gateway | CNAME | `sygnal` | - | - | - | `matrix.example.com` | +| [ntfy](configuring-playbook-ntfy.md) push notifications server | CNAME | `ntfy` | - | - | - | `matrix.example.com` | +| [Etherpad](configuring-playbook-etherpad.md) collaborative text editor | CNAME | `etherpad` | - | - | - | `matrix.example.com` | +| [Hydrogen](configuring-playbook-client-hydrogen.md) web client | CNAME | `hydrogen` | - | - | - | `matrix.example.com` | +| [Cinny](configuring-playbook-client-cinny.md) web client | CNAME | `cinny` | - | - | - | `matrix.example.com` | +| [SchildiChat](configuring-playbook-client-schildichat.md) web client | CNAME | `schildichat` | - | - | - | `matrix.example.com` | +| [wsproxy](configuring-playbook-bridge-mautrix-wsproxy.md) sms bridge | CNAME | `wsproxy` | - | - | - | `matrix.example.com` | +| [Buscarron](configuring-playbook-bot-buscarron.md) helpdesk bot | CNAME | `buscarron` | - | - | - | `matrix.example.com` | +| [rageshake](docs/configuring-playbook-rageshake.md) bug report server | CNAME | `rageshake` | - | - | - | `matrix.example.com` | +| [Postmoogle](configuring-playbook-bridge-postmoogle.md)/[Email2Matrix](configuring-playbook-email2matrix.md) email bridges | MX | `matrix` | 10 | 0 | - | `matrix.example.com` | +| [Postmoogle](configuring-playbook-bridge-postmoogle.md) email bridge | TXT | `matrix` | - | - | - | `v=spf1 ip4: -all` | +| [Postmoogle](configuring-playbook-bridge-postmoogle.md) email bridge | TXT | `_dmarc.matrix` | - | - | - | `v=DMARC1; p=quarantine;` | +| [Postmoogle](configuring-playbook-bridge-postmoogle.md) email bridge | TXT | `postmoogle._domainkey.matrix` | - | - | - | get it from `!pm dkim` | When setting up a SRV record, if you are asked for a service and protocol instead of a hostname split the host value from the table where the period is. For example use service as `_matrix-identity` and protocol as `_tcp`. @@ -97,4 +97,4 @@ When you're done with the DNS configuration and ready to proceed, continue with ## `_dmarc`, `postmoogle._domainkey` TXT and `matrix` MX records setup -To make the [postmoogle](configuring-playbook-bot-postmoogle.md) email bridge enable its email sending features, you need to configure SPF (TXT), DMARC (TXT), DKIM (TXT) and MX records +To make the [postmoogle](configuring-playbook-bridge-postmoogle.md) email bridge enable its email sending features, you need to configure SPF (TXT), DMARC (TXT), DKIM (TXT) and MX records diff --git a/docs/configuring-playbook-bot-postmoogle.md b/docs/configuring-playbook-bridge-postmoogle.md similarity index 77% rename from docs/configuring-playbook-bot-postmoogle.md rename to docs/configuring-playbook-bridge-postmoogle.md index 5d12f7b2a..4a7f31c26 100644 --- a/docs/configuring-playbook-bot-postmoogle.md +++ b/docs/configuring-playbook-bridge-postmoogle.md @@ -4,7 +4,7 @@ The playbook can install and configure [Postmoogle](https://github.com/etkecc/postmoogle) for you. -Postmoogle is a bot/bridge you can use to forward emails to Matrix rooms. It runs an SMTP email server and allows you to assign mailbox addresses to Matrix rooms. +Postmoogle is a bridge you can use to have its bot user forward emails to Matrix rooms. It runs an SMTP email server and allows you to assign mailbox addresses to the rooms. See the project's [documentation](https://github.com/etkecc/postmoogle) to learn what it does and why it might be useful to you. @@ -57,18 +57,18 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use **Notes**: -- the `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account +- the `ensure-matrix-users-created` playbook tag makes the playbook automatically create a user account of the bridge's bot -- if you change the bot password (`matrix_bot_postmoogle_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `matrix_bot_postmoogle_password` to let the bot know its new password +- if you change the bridge's bot password (`matrix_bot_postmoogle_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [synapse-admin](configuring-playbook-synapse-admin.md) to change it, and then update `matrix_bot_postmoogle_password` to let the bot know its new password ## Usage -To use the bot, invite the `@postmoogle:example.com` bot user into a room you want to use as a mailbox. +To use the bridge, invite the `@postmoogle:example.com` bot user into a room you want to use as a mailbox. Then send `!pm mailbox NAME` to expose this Matrix room as an inbox with the email address `NAME@matrix.example.com`. Emails sent to that email address will be forwarded to the room. -Send `!pm help` to the room to see the bot's help menu for additional commands. +Send `!pm help` to the room to see the bridge's help menu for additional commands. You can also refer to the upstream [documentation](https://github.com/etkecc/postmoogle). diff --git a/docs/configuring-playbook-email2matrix.md b/docs/configuring-playbook-email2matrix.md index fa56b8c82..ab274afe4 100644 --- a/docs/configuring-playbook-email2matrix.md +++ b/docs/configuring-playbook-email2matrix.md @@ -1,6 +1,6 @@ # Setting up Email2Matrix (optional) -**Note**: email bridging can also happen via the [Postmoogle](configuring-playbook-bot-postmoogle.md) bot supported by the playbook. Postmoogle is much more powerful and easier to use, so we recommend that you use it, instead of Email2Matrix. +**Note**: email bridging can also happen via the [Postmoogle](configuring-playbook-bridge-postmoogle.md) bridge supported by the playbook. Postmoogle is much more powerful and easier to use, so we recommend that you use it, instead of Email2Matrix. The playbook can install and configure [email2matrix](https://github.com/devture/email2matrix) for you. diff --git a/docs/configuring-playbook-matrix-authentication-service.md b/docs/configuring-playbook-matrix-authentication-service.md index d83bdf58a..625b3116e 100644 --- a/docs/configuring-playbook-matrix-authentication-service.md +++ b/docs/configuring-playbook-matrix-authentication-service.md @@ -51,7 +51,7 @@ This section details what you can expect when switching to the Matrix Authentica - ❌ Certain **tools like [synapse-admin](./configuring-playbook-synapse-admin.md) do not have full compatibility with MAS yet**. synapse-admin already supports [login with access token](https://github.com/etkecc/synapse-admin/pull/58), browsing users (which Synapse will internally fetch from MAS) and updating user avatars. However, editing users (passwords, etc.) now needs to happen directly against MAS using the [MAS Admin API](https://element-hq.github.io/matrix-authentication-service/api/index.html), which synapse-admin cannot interact with yet. -- ❌ **Some services** (e.g. [Postmoogle](./configuring-playbook-bot-postmoogle.md), but possibly others - the list is yet to be determined) appear to **experience issues when authenticating via MAS**. We're still investigating what breaks and why. +- ❌ **Some services** (e.g. [Postmoogle](./configuring-playbook-bridge-postmoogle.md), but possibly others - the list is yet to be determined) appear to **experience issues when authenticating via MAS**. We're still investigating what breaks and why. - ❌ **Encrypted appservices** do not work yet (related to [MSC4190](https://github.com/matrix-org/matrix-spec-proposals/pull/4190) and [PR 17705 for Synapse](https://github.com/element-hq/synapse/pull/17705)), so all bridges/bots that rely on encryption will fail to start (see [this issue](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/3658) for Hookshot). You can use these bridges/bots only if you **keep end-to-bridge encryption disabled** (which is the default setting). diff --git a/docs/configuring-playbook.md b/docs/configuring-playbook.md index 22341ef84..38e7b0847 100644 --- a/docs/configuring-playbook.md +++ b/docs/configuring-playbook.md @@ -167,7 +167,7 @@ When you're done with all the configuration you'd like to do, continue with [Ins - [Setting up Email2Matrix](configuring-playbook-email2matrix.md) (optional) -- [Setting up Postmoogle email bridging](configuring-playbook-bot-postmoogle.md) (optional) +- [Setting up Postmoogle email bridging](configuring-playbook-bridge-postmoogle.md) (optional) - [Setting up Matrix SMS bridging](configuring-playbook-bridge-matrix-bridge-sms.md) (optional) diff --git a/roles/custom/matrix-bot-postmoogle/defaults/main.yml b/roles/custom/matrix-bot-postmoogle/defaults/main.yml index 19d1590c5..faade072c 100644 --- a/roles/custom/matrix-bot-postmoogle/defaults/main.yml +++ b/roles/custom/matrix-bot-postmoogle/defaults/main.yml @@ -1,5 +1,5 @@ --- -# postmoogle is an email to Matrix bot +# postmoogle is an email to Matrix bridge using its bot user # Project source code URL: https://github.com/etkecc/postmoogle matrix_bot_postmoogle_enabled: true