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.

Sign up for GitHub

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

Closed
wants to merge 5 commits into from
Closed

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

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
1503640
enable bridge-encryption
whowantsmybigdata Oct 14, 2022
4bd005f
added usage scenario
whowantsmybigdata Oct 14, 2022
d84e1bb
Update configuring-playbook-turn.md
whowantsmybigdata Oct 14, 2022
cc8805f
Edit postmoogle docs
whowantsmybigdata Oct 15, 2022
c9c6f71
updated postmoogle and signal-docs-edits
whowantsmybigdata Oct 15, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 21 additions & 1 deletion docs/configuring-playbook-bot-postmoogle.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,12 @@ matrix_bot_postmoogle_password: PASSWORD_FOR_THE_BOT
You will need to add several DNS records
See [Configuring DNS](configuring-dns.md).

To be able to get the value for `!pm dkim` for your DNS settings you need to have admin-rights for the bridge:
To be able to get the value for `!pm dkim` for your DNS settings you need to have admin-rights for the bridge.
If you didn't set this generally for all bridges with:
```yaml
matrix_admin: "@username:{{ matrix_domain }}"
```
you need to set one for administering postmoogle with this item in your `vars.yml`:
```yaml
matrix_bot_postmoogle_admins:
- "@<username>:{{ matrix_domain }}"
Expand Down Expand Up @@ -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.


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: ""
```
Comment on lines +81 to +85
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?


If you want to enforce TLS on both ports add this to `vars.yml`:
```yaml
matrix_bot_postmoogle_tls_required: true
```
Comment on lines +87 to +90
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


## Installing

After configuring the playbook, run the [installation](installing.md) command again:
Expand Down
10 changes: 9 additions & 1 deletion docs/configuring-playbook-bridge-mautrix-signal.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,15 @@ As seen in the mentioned [upstream-documentation](https://docs.mau.fi/bridges/py
- `allow: true` the bridge won't enable encryption on its own, but will work in encrypted rooms
- `default: true` the bridge will automatically enable encryption in new portals.

**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.
**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.
Comment on lines +96 to +104
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.


## Usage

Expand Down