2018-11-26 05:23:42 +00:00
# Setting up Matrix Corporal (optional, advanced)
-------------------------------------
**WARNING**: This is an advanced feature! It requires prior experience with Matrix and a specific need for using [Matrix Corporal ](https://github.com/devture/matrix-corporal ). If you're unsure whether you have such a need, you most likely don't.
-------------------------------------
2018-08-21 10:34:34 +00:00
The playbook can install and configure [matrix-corporal ](https://github.com/devture/matrix-corporal ) for you.
2024-12-17 09:23:37 +00:00
In short, it's a sort of automation and firewalling service, which is helpful if you're instaling Matrix services in a controlled corporate environment.
See the project's [documentation ](https://github.com/devture/matrix-corporal/blob/main/README.md ) to learn what it does and why it might be useful to you.
2018-08-21 10:34:34 +00:00
2021-01-16 21:47:14 +00:00
If you decide that you'd like to let this playbook install it for you, you'd need to also:
- (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 )
2018-08-21 10:34:34 +00:00
2024-10-12 11:48:24 +00:00
## Adjusting the playbook configuration
2020-08-19 06:29:39 +00:00
2024-10-17 13:17:56 +00:00
Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs):
2018-08-21 10:34:34 +00:00
```yaml
2020-08-19 06:29:39 +00:00
# The Shared Secret Auth password provider module is required for Corporal to work.
# See configuring-playbook-shared-secret-auth.md
matrix_synapse_ext_password_provider_shared_secret_auth_enabled: true
matrix_synapse_ext_password_provider_shared_secret_auth_shared_secret: YOUR_SHARED_SECRET_GOES_HERE
2021-01-16 21:47:14 +00:00
# When matrix-corporal is acting as the primary authentication provider,
# you need to set up the REST authentication password provider module
# to make Interactive User Authentication work.
# This is necessary for certain user actions (like E2EE, device management, etc).
#
# See configuring-playbook-rest-auth.md
matrix_synapse_ext_password_provider_rest_auth_enabled: true
matrix_synapse_ext_password_provider_rest_auth_endpoint: "http://matrix-corporal:41080/_matrix/corporal"
2018-08-21 10:34:34 +00:00
matrix_corporal_enabled: true
2021-11-15 08:29:25 +00:00
# See below for an example of how to use a locally-stored static policy
2018-08-21 10:34:34 +00:00
matrix_corporal_policy_provider_config: |
{
"Type": "http",
"Uri": "https://intranet.example.com/matrix/policy",
"AuthorizationBearerToken": "SOME_SECRET",
"CachePath": "/var/cache/matrix-corporal/last-policy.json",
2020-04-29 14:22:18 +00:00
"ReloadIntervalSeconds": 1800,
"TimeoutMilliseconds": 300
2018-08-21 10:34:34 +00:00
}
# If you also want to enable Matrix Corporal's HTTP API..
matrix_corporal_http_api_enabled: true
matrix_corporal_http_api_auth_token: "AUTH_TOKEN_HERE"
2024-10-15 17:24:34 +00:00
# If you need to change matrix-corporal's user ID from the default (matrix-corporal).
2018-10-23 06:19:24 +00:00
# In any case, you need to make sure this Matrix user is created on your server.
2021-01-16 21:47:14 +00:00
matrix_corporal_corporal_user_id_local_part: "matrix-corporal"
2019-04-01 18:40:14 +00:00
# Because Corporal peridoically performs lots of user logins from the same IP,
# you may need raise Synapse's ratelimits.
# The values below are just an example. Tweak to your use-case (number of users, etc.)
matrix_synapse_rc_login:
address:
per_second: 50
burst_count: 300
account:
per_second: 0.17
burst_count: 3
failed_attempts:
per_second: 0.17
burst_count: 3
2018-08-21 10:34:34 +00:00
```
2024-10-18 17:32:11 +00:00
Matrix Corporal operates with a specific Matrix user on your server. By default, it's `matrix-corporal` (controllable by the `matrix_corporal_reconciliation_user_id_local_part` setting, see above).
2024-10-15 17:24:34 +00:00
No matter what Matrix user ID you configure to run it with, make sure that:
2018-10-23 06:19:24 +00:00
2021-11-15 08:29:25 +00:00
- the Matrix Corporal user is created by [registering it ](registering-users.md ) **with administrator privileges** . Use a password you remember, as you'll need to log in from time to time to create or join rooms
2018-10-23 06:19:24 +00:00
- the Matrix Corporal user is joined and has Admin/Moderator-level access to any rooms you want it to manage
2021-11-15 08:29:25 +00:00
### Using a locally-stored static policy
If you'd like to use a [static policy file ](https://github.com/devture/matrix-corporal/blob/master/docs/policy-providers.md#static-file-pull-style-policy-provider ), you can use a configuration like this:
```yaml
matrix_corporal_policy_provider_config: |
{
"Type": "static_file",
"Path": "/etc/matrix-corporal/policy.json"
}
# Modify the policy below as you see fit
2023-05-12 04:00:58 +00:00
aux_file_definitions:
2021-11-15 08:29:25 +00:00
- dest: "{{ matrix_corporal_config_dir_path }}/policy.json"
content: |
{
"schemaVersion": 1,
"identificationStamp": "stamp-1",
"flags": {
"allowCustomUserDisplayNames": false,
"allowCustomUserAvatars": false,
"forbidRoomCreation": false,
"forbidEncryptedRoomCreation": true,
"forbidUnencryptedRoomCreation": false,
"allowCustomPassthroughUserPasswords": true,
"allowUnauthenticatedPasswordResets": false,
"allow3pidLogin": false
},
"managedCommunityIds": [],
"managedRoomIds": [],
"users": []
}
```
To learn more about what the policy configuration, see the matrix-corporal documentation on [policy ](https://github.com/devture/matrix-corporal/blob/master/docs/policy.md ).
2024-10-12 18:03:46 +00:00
## Installing
2024-12-01 07:42:30 +00:00
After configuring the playbook, run it with [playbook tags ](playbook-tags.md ) as below:
2021-11-15 08:29:25 +00:00
2024-12-01 07:42:30 +00:00
<!-- NOTE: let this conservative command run (instead of install - all) to make it clear that failure of the command means something is clearly broken. -->
```sh
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
```
Edit installing instructions (#3844)
* Replace "just run-tags install-all/setup-all,start" with "just install-all/setup-all"
Thanks to the tip by Slavi that the overhead of ensure-matrix-users-created is negligible.
Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
* Edit installing instructions
- Move the anchor links to docs/just.md
- Add note about running "ensure-matrix-users-created" tags, if ansible-playbook's tags not "setup-all,ensure-matrix-users-created,start", ie. either "setup-all,start", "setup-email2matrix,start", "setup-aux-files,setup-corporal,start", or "setup-matrix-user-verification-service,start"
Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
* Update descriptions about installation
- Introduce the most conservative and stable raw ansible-playbook command.
- Introduce the just commands on installing.md and maintenance-upgrading-services.md, not on quick-start.md, since it is too early for quick start guide readers who are just starting to climb learning curve to use the shortcuts.
Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
* Update docs/configuring-playbook-etherpad.md: remove the note about ensure-matrix-users-created
Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
---------
Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
Co-authored-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
2024-12-01 15:04:54 +00:00
The shortcut commands with the [`just` program ](just.md ) are also available: `just run-tags setup-aux-files,setup-corporal,start` or `just setup-all`
2024-12-01 07:42:30 +00:00
Edit installing instructions (#3844)
* Replace "just run-tags install-all/setup-all,start" with "just install-all/setup-all"
Thanks to the tip by Slavi that the overhead of ensure-matrix-users-created is negligible.
Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
* Edit installing instructions
- Move the anchor links to docs/just.md
- Add note about running "ensure-matrix-users-created" tags, if ansible-playbook's tags not "setup-all,ensure-matrix-users-created,start", ie. either "setup-all,start", "setup-email2matrix,start", "setup-aux-files,setup-corporal,start", or "setup-matrix-user-verification-service,start"
Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
* Update descriptions about installation
- Introduce the most conservative and stable raw ansible-playbook command.
- Introduce the just commands on installing.md and maintenance-upgrading-services.md, not on quick-start.md, since it is too early for quick start guide readers who are just starting to climb learning curve to use the shortcuts.
Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
* Update docs/configuring-playbook-etherpad.md: remove the note about ensure-matrix-users-created
Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
---------
Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
Co-authored-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
2024-12-01 15:04:54 +00:00
`just run-tags setup-aux-files,setup-corporal,start` is useful for maintaining your setup quickly when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all` , or these components will still remain installed. Note `just setup-all` runs the `ensure-matrix-users-created` tag too.
2018-10-24 10:59:06 +00:00
2018-10-23 06:19:24 +00:00
## Matrix Corporal files
2018-08-21 10:34:34 +00:00
The following local filesystem paths are mounted in the `matrix-corporal` container and can be used in your configuration (or policy):
- `/matrix/corporal/config` is mounted at `/etc/matrix-corporal` (read-only)
- `/matrix/corporal/var` is mounted at `/var/matrix-corporal` (read and write)
- `/matrix/corporal/cache` is mounted at `/var/cache/matrix-corporal` (read and write)
2018-10-23 06:19:24 +00:00
2021-02-16 08:44:35 +00:00
As an example: you can create your own configuration files in `/matrix/corporal/config` and they will appear in `/etc/matrix-corporal` in the Docker container. Your configuration (stuff in `matrix_corporal_policy_provider_config` ) needs to refer to these files via the local container paths - `/etc/matrix-corporal` (read-only), `/var/matrix-corporal` (read and write), `/var/cache/matrix-corporal` (read and write).