Skip to content

Commit 2c80aaf

Browse files
author
Suguru Hirahara
committed
Edit docs/configuring-playbook-email2matrix.md: adopt the common instruction
Based on docs/configuring-playbook-dimension.md and docs/configuring-playbook-bot-go-neb.md Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
1 parent 4798888 commit 2c80aaf

File tree

1 file changed

+21
-12
lines changed

1 file changed

+21
-12
lines changed

docs/configuring-playbook-email2matrix.md

Lines changed: 21 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -22,11 +22,25 @@ If you really need to run an email server on the Matrix machine for other purpos
2222

2323
For details about using Email2Matrix alongside [Postfix](http://www.postfix.org/), see [here](https://github.com/devture/email2matrix/blob/master/docs/setup_with_postfix.md).
2424

25-
### Creating a user
25+
### Register a dedicated Matrix user (optional)
2626

27-
Before enabling Email2Matrix, you'd most likely wish to create a dedicated user (or more) that would be sending messages on the Matrix side. Take note of the user's ID as it needs to be specified as `MatrixUserId` on your `inventory/host_vars/matrix.example.com/vars.yml` file later.
27+
We recommend that you create a dedicated Matrix user for Email2Matrix.
2828

29-
Refer to [Registering users](registering-users.md) for ways to create a user. A regular (non-admin) user works best.
29+
Generate a strong password for the user. You can create one with a command like `pwgen -s 64 1`.
30+
31+
You can use the playbook to [register a new user](registering-users.md):
32+
33+
```sh
34+
ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=email2matrix password=PASSWORD_FOR_THE_USER admin=no' --tags=register-user
35+
```
36+
37+
Take note of the user's ID as it needs to be specified as `MatrixUserId` on your `inventory/host_vars/matrix.example.com/vars.yml` file later.
38+
39+
### Obtain an access token
40+
41+
Email2Matrix requires an access token for the sender user to be able to send messages to the room. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
42+
43+
⚠️ **Warning**: Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone.
3044

3145
### Creating a shared room
3246

@@ -38,25 +52,20 @@ Inviting additional people to the room is okay too.
3852

3953
Take note of each room's room ID (different clients show the room ID in a different place). You'll need the room ID when [configuring the playbook](#adjusting-the-playbook-configuration) below.
4054

41-
### Obtain an access token for the sender user
42-
43-
In order for the sender user created above to be able to send messages to the room, we'll need to obtain an access token for it. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
44-
45-
⚠️ **Warning**: Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone.
46-
4755
## Adjusting the playbook configuration
4856

49-
After doing the preparation steps above, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
57+
To enable Email2Matrix, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `ACCESS_TOKEN_FOR_EMAIL2MATRIX1_HERE` and `ACCESS_TOKEN_FOR_EMAIL2MATRIX2_HERE` with the ones created [above](#obtain-an-access-token).
5058

5159
```yaml
5260
matrix_email2matrix_enabled: true
5361

62+
# You need at least 1 mailbox.
5463
matrix_email2matrix_matrix_mappings:
5564
- MailboxName: "mailbox1"
5665
MatrixRoomId: "!qporfwt:{{ matrix_domain }}"
5766
MatrixHomeserverUrl: "{{ matrix_homeserver_url }}"
5867
MatrixUserId: "@email2matrix1:{{ matrix_domain }}"
59-
MatrixAccessToken: "MATRIX_ACCESS_TOKEN_HERE"
68+
MatrixAccessToken: "ACCESS_TOKEN_FOR_EMAIL2MATRIX1_HERE"
6069
IgnoreSubject: false
6170
IgnoreBody: false
6271
SkipMarkdown: false
@@ -65,7 +74,7 @@ matrix_email2matrix_matrix_mappings:
6574
MatrixRoomId: "!aaabaa:{{ matrix_domain }}"
6675
MatrixHomeserverUrl: "{{ matrix_homeserver_url }}"
6776
MatrixUserId: "@email2matrix2:{{ matrix_domain }}"
68-
MatrixAccessToken: "MATRIX_ACCESS_TOKEN_HERE"
77+
MatrixAccessToken: "ACCESS_TOKEN_FOR_EMAIL2MATRIX2_HERE"
6978
IgnoreSubject: true
7079
IgnoreBody: false
7180
SkipMarkdown: true

0 commit comments

Comments
 (0)