Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Edit docs for signal-bridge, coturn, postmoogle #2174

Open
wants to merge 5 commits into
base: master
Choose a base branch
from

Conversation

whowantsmybigdata
Copy link

@whowantsmybigdata whowantsmybigdata commented Oct 14, 2022

  • add how to enable signal-bridge to work with encryption. I think this would maybe work for other python-based mautrix-bridges? (just tested with mautrix-signal)

  • add another usage scenario, how to add signal-contacts to matrix-rooms (for me was neither clear from this docs nor the upstream ones)

  • add solution for problematic use-case scenario when setting up coturn with manually managed lets-encrypt certs

  • add info to set postmoogle-admin, to get !pm dkim to work

  • add infos to set up postmoogle with self-managed ssl

added how to enable the bridge to work with encryption, wasn't working out-of-the-box
@whowantsmybigdata whowantsmybigdata changed the title Edit docs for signal-bridge Edit docs for signal-bridge and Coturn Oct 14, 2022
@whowantsmybigdata whowantsmybigdata changed the title Edit docs for signal-bridge and Coturn Edit docs for signal-bridge, coturn, postmoogle Oct 15, 2022
@@ -69,6 +74,21 @@ matrix_bot_postmoogle_tls_key: ""
```
**Note:** `matrix_bot_postmoogle_ssl_path:` defaults to what you set for `matrix_ssl_config_dir_path:` As seen in [/group_vars/matrix_servers](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/group_vars/matrix_servers#L1213) but it has to be set again to make postmoogle look for it outside the docker-container.

## Open Ports
If you run a firewall on your server and/or it sits behind a NAT-Router, remember to open/forward the ports `25` (for non-TLS) and `587` (TLS)
as set [here](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/roles/matrix-bot-postmoogle/defaults/main.yml#L121)
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This link to master is a moving target. Line 121 will change sooner or later.

You'd better link to a specific commit, or not link there are all. It's better to mention the file (roles/matrix-bot-postmoogle/defaults/main.yml) and variables and their default values, but... in this case, it's useless.

Changing these ports is something that most people don't need to do. It's a good way to make your server not work well with the rest of the world.

Comment on lines +81 to +85
It's possible to change those ports in `vars.yml` with:
```yaml
matrix_bot_postmoogle_smtp_host_bind_port: ""
matrix_bot_postmoogle_submission_host_bind_port: ""
```
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't see how this is helpful. Why do most users need to change the standard ports that email operates on?

Comment on lines +87 to +90
If you want to enforce TLS on both ports add this to `vars.yml`:
```yaml
matrix_bot_postmoogle_tls_required: true
```
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This also seems unrelated to the "Open ports" section, which deals with telling people what ports to open in their firewall for Postmoogle to work.

There are many other variables that we may wish to mention on this documentation page, but.. it's better to point the user to the defaults/main.yml file (and the upstream Postmoogle docs) and have them discover options there.

Important options could be mentioned, but I'm not sure this is an important one.

Seeing it, it also makes me think "How do I know if I want to enforce TLS? Is it better to do it?"

.. and I suspect the answer to this one is:

  • people who know the answer will likely find this variable and toggle it
  • most people don't care
  • not enforcing is probably better for compatibility

Comment on lines +96 to +104
**Note**:
* [Upstream-documentation](https://docs.mau.fi/bridges/python/signal/index.html) mentions to make sure using postgres if enabling the bridge in encrypted rooms.
* Careful when setting `matrix_mautrix_signal_configuration_extension_yaml:`: If you already used this item before for setting permissions add the part:
```
encryption:
allow: true
default: true
```
below the permission-part.
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Indentantion is broken in the YAML block (mixing tabs and spaces).

You also seem to be basing this PR on some older commit.. We don't have an Enable End-to-End-Encryption section in docs/configuring-playbook-bridge-mautrix-signal.md anymore.

We do have a a new docs page that applies to all mautrix bridges: docs/configuring-playbook-mautrix-bridges.md, which explains how to enable end-to-end encryption.

It'd be better if we link to docs/configuring-playbook-mautrix-bridges.md from each mautrix bridge page, to make it more discoverable. It seems like we're not doing it yet.

@luixxiul luixxiul added the needs-info This issue is blocked awaiting information from the reporter label Nov 2, 2024
Copy link

This PR is stale because it has been open a year with no activity. Remove stale label or this will be closed in 30 days.

@github-actions github-actions bot added the stale label Nov 25, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
needs-info This issue is blocked awaiting information from the reporter needs-rebase stale
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants