mirror of
https://github.com/famedly/ansible-collection-matrix
synced 2024-09-20 22:11:54 +00:00
docs: improve wording, formatting and provide more hyperlinks for easier navigation
This commit is contained in:
transcaffeine
parent
0a4af363d3
commit
59d1f76e87
2 changed files with 86 additions and 62 deletions
57
README.md
57
README.md
|
|
@ -1,28 +1,47 @@
|
|||
# Ansible Collection - famedly.matrix
|
||||
# Ansible Collection - `famedly.matrix`
|
||||
|
||||
## Modules
|
||||
This collection contains a few modules for managing matrix rooms and
|
||||
servers, as well as sending notifications from ansible to matrix.
|
||||
|
||||
- **matrix\_login**: Create an access token for a matrix account.
|
||||
- **matrix\_logout**: Invalidates an access token.
|
||||
- **matrix\_notification**: Sends a message to a matrix room.
|
||||
- **matrix\_room**: Idempotently joins/creates a room with a given
|
||||
alias.
|
||||
- **matrix\_state**: Ensures room state has a given content.
|
||||
- **matrix\_member**: Ensures room memberships are correct.
|
||||
- **matrix\_signing\_key**: Creates a server signing key.
|
||||
- **synapse\_register**: Registers a user using synapse's admin API.
|
||||
This collection contains modules for managing matrix rooms
|
||||
and more via ansible. They can modify room membership,
|
||||
aliases, server signing keys and even send messages into
|
||||
rooms from within ansible.
|
||||
|
||||
You can find more information and a sample playbook for these modules in the
|
||||
README in `./plugins/modules/`
|
||||
- [`matrix_login` (source)](plugins/modules/matrix_login.py):
|
||||
Create an access token for a matrix account.
|
||||
- [`matrix_login` (source)](plugins/modules/matrix_login.py):
|
||||
Create an access token for a matrix account.
|
||||
Logs in with user and password to obtain a matrix access token
|
||||
- [`matrix_uia_login` (source)](plugins/modules/matrix_uia_login.py):
|
||||
Logs in with user and password to obtain a matrix access token, while
|
||||
implementing [user-interactive authentication](https://spec.matrix.org/unstable/client-server-api/#user-interactive-authentication-api)
|
||||
on the `_matrix/client/r0/login` endpoint (see [MSC2835](https://github.com/Sorunome/matrix-doc/blob/soru/uia-on-login/proposals/2835-uia-on-login.md)).
|
||||
- [`matrix_logout` (source)](plugins/modules/matrix_logout.py):
|
||||
Invalidates an access token.
|
||||
- [`matrix_notification` (source)](plugins/modules/matrix_notification.py):
|
||||
Sends a message to a matrix room.
|
||||
- [`matrix_room` (source)](plugins/modules/matrix_room.py):
|
||||
Idempotently joins/creates a room with a given alias.
|
||||
- [`matrix_state` (source)](plugins/modules/matrix_state.py):
|
||||
Can be used to set matrix state events to a room.
|
||||
- [`matrix_member` (source)](plugins/modules/matrix_member.py):
|
||||
Can be used to manipulate matrix room membership.
|
||||
- [`matrix_signing_key` (source)](plugins/modules/matrix_signing_key.py):
|
||||
Creates a server signing key.
|
||||
- [`synapse_register` (source)](plugins/modules/synapse_register.py):
|
||||
Registers a user using synapse's admin API.
|
||||
|
||||
For more information on how to use the modules to manage matrix rooms
|
||||
via ansible, the [README in `./plugins/modules/`](plugins/modules/README.md)
|
||||
provides more detailed information and an example playbook.
|
||||
|
||||
## Roles
|
||||
In addition to the modules, this role *also* contains a few roles for
|
||||
deploying commonly used matrix services:
|
||||
|
||||
- **synapse**: Homeserver, this is where your accounts live.
|
||||
- **element**: Web client, for using your accounts.
|
||||
|
||||
For details on using these, look at the README.md in the respective
|
||||
role directory.
|
||||
- [`synapse`](roles/synapse/README.md): synapse, a reference matrix homeserver
|
||||
implementation in python, maintained mostly by element.
|
||||
- [`element`](roles/element/README.md): element-web, a reference matrix client implementation,
|
||||
able to run in the browser, maintained by element.
|
||||
- [`hedwig`](roles/hedwig/README.md): Hedwig, a push-gateway server alternative
|
||||
to `sygnal`, developed by Famedly.
|
||||
|
|
|
|||
|
|
@ -1,67 +1,72 @@
|
|||
# matrix-synapse
|
||||
|
||||
Install a matrix synapse server.
|
||||
Deploy [synapse](https://github.com/matrix-org/synapse/), a matrix homeserver implementation in python, using ansible.
|
||||
|
||||
The role supports deployment both as systemd-services or as a docker container.
|
||||
|
||||
## Requirements
|
||||
|
||||
The following should be present on the target system
|
||||
The following should be present on the target system when deploying synapse as a systemd service:
|
||||
* `pip`
|
||||
* `systemd`
|
||||
* `rsyslogd`
|
||||
* `logrotate`
|
||||
|
||||
If deploying synapse in a docker container, check that you have `docker` and the corresponding python-bindings (usually
|
||||
`python3-docker`) installed.
|
||||
|
||||
## Role Variables
|
||||
|
||||
### Mandatory Variables
|
||||
|
||||
| Name | Type | Description |
|
||||
| :--- | :--- | :--- |
|
||||
| **matrix_server_name** | __string__ | |
|
||||
| **matrix_synapse_tls_cert** | __string__ | server's TLS certificate chain (_when matrix_synapse_extra_config.no_tls is set to true_) |
|
||||
| **matrix_synapse_tls_key** | __string__ | server's TLS key (_when matrix_synapse_extra_config.no_tls is set to true_) |
|
||||
| **matrix_synapse_report_stats** | __bool__ | Report the stats to matrix.org |
|
||||
| **matrix_synapse_pg_host** | __string__ | postgresql server |
|
||||
| **matrix_synapse_pg_user** | __string__ | postgresql user |
|
||||
| **matrix_synapse_pg_pass** | __string__ | postgresql user's password |
|
||||
| **matrix_synapse_pg_db** | __string__ | postgresql database |
|
||||
| Name | Type | Description |
|
||||
| :--- | :--- | :--- |
|
||||
| `matrix_server_name` | __string__ | |
|
||||
| `matrix_synapse_tls_cert` | __string__ | server's TLS certificate chain (_when `matrix_synapse_extra_config.no_tls` is set to true_) |
|
||||
| `matrix_synapse_tls_key` | __string__ | server's TLS key (_when `matrix_synapse_extra_config.no_tls` is set to true_) |
|
||||
| `matrix_synapse_report_stats` | __bool__ | Wether to report homeserver usage stats to matrix.org |
|
||||
| `matrix_synapse_pg_host` | __string__ | postgresql server |
|
||||
| `matrix_synapse_pg_user` | __string__ | postgresql user |
|
||||
| `matrix_synapse_pg_pass` | __string__ | postgresql user's password |
|
||||
| `matrix_synapse_pg_db` | __string__ | postgresql database |
|
||||
|
||||
### Optional Variables
|
||||
|
||||
| Name | Value | Description |
|
||||
| :--- | :--- | :--- |
|
||||
| matrix_synapse_base_path | "/opt/synapse" | |
|
||||
| matrix_synapse_secrets_path | "{{ matrix_synapse_base_path }}/secrets" | |
|
||||
| matrix_synapse_extra_config | _None_ | configuration parameters as given in the [synapse configuration file](https://github.com/matrix-org/synapse/tree/master/docs) |
|
||||
| matrix_synapse_dh_path | "{{ matrix_synapse_base_path }}/tls/{{ matrix_server_name }}.dh" | |
|
||||
| matrix_synapse_public_baseurl | "https://{{ matrix_server_name }}" | |
|
||||
| matrix_synapse_signing_key_path | "{{ matrix_synapse_base_path }}/ssl/{{ matrix_server_name }}.signing.key" | |
|
||||
| matrix_synapse_version | "v1.30.1" | |
|
||||
| matrix_synapse_unstable | false | when true, release candidate versions are deployed too |
|
||||
| matrix_synapse_log_days_keep | 14 | |
|
||||
| matrix_synapse_deployment_method | pip | Either pip or docker [¹](#footnote_1) |
|
||||
| matrix_synapse_supervision_method | systemd | Either systemd, runit or docker [¹](#footnote_1) |
|
||||
| matrix_synapse_python_version | 3 | Default python version (2, 3) to be used |
|
||||
| matrix_synapse_redis_enabled | false | If synapse should connect to redis (needed for workers) |
|
||||
| matrix_synapse_redis_host | _None_ | host on which redis is running |
|
||||
| matrix_synapse_redis_port | 6379 | port on which redis is running |
|
||||
| matrix_synapse_redis_pass | _None_ | password to use to authentificate to redis |
|
||||
| Name | Default value | Description |
|
||||
| :--- | :--- | :--- |
|
||||
| `matrix_synapse_base_path` | "/opt/synapse" | |
|
||||
| `matrix_synapse_secrets_path` | "{{ matrix_synapse_base_path }}/secrets" | |
|
||||
| `matrix_synapse_extra_config` | _None_ | configuration parameters as given in the [synapse configuration file](https://github.com/matrix-org/synapse/tree/master/docs) |
|
||||
| `matrix_synapse_dh_path` | "{{ matrix_synapse_base_path }}/tls/{{ matrix_server_name }}.dh" | |
|
||||
| `matrix_synapse_public_baseurl` | "https://{{ matrix_server_name }}" | |
|
||||
| `matrix_synapse_signing_key_path` | "{{ matrix_synapse_base_path }}/ssl/{{ matrix_server_name }}.signing.key" | |
|
||||
| `matrix_synapse_version` | "v1.30.1" | |
|
||||
| `matrix_synapse_unstable` | false | when true, release candidate versions are deployed too |
|
||||
| `matrix_synapse_log_days_keep` | 14 | |
|
||||
| `matrix_synapse_deployment_method` | pip | Either pip or docker [¹](#footnote_1) |
|
||||
| `matrix_synapse_supervision_method` | systemd | Either systemd, runit or docker [¹](#footnote_1) |
|
||||
| `matrix_synapse_python_version` | 3 | Default python version (2, 3) to be used |
|
||||
| `matrix_synapse_redis_enabled` | false | If synapse should connect to redis (needed for workers) |
|
||||
| `matrix_synapse_redis_host` | _None_ | host on which redis is running |
|
||||
| `matrix_synapse_redis_port` | 6379 | port on which redis is running |
|
||||
| `matrix_synapse_redis_pass` | _None_ | password to use to authentificate to redis |
|
||||
|
||||
|
||||
### Worker control variables
|
||||
|
||||
| Name | Value | Description |
|
||||
| :--- | :--- | :--- |
|
||||
| matrix_synapse_workers_enabled | `false` | Enables workers and starts the replication listener |
|
||||
| matrix_synapse_workers_client | `0` | Amount of workers to deploy which serve the client API |
|
||||
| matrix_synapse_workers_federation_in | `0` | Amount of federation workers to deploy (inbound) |
|
||||
| matrix_synapse_workers_federation_out | `0` | Amount of federation sender workers to deploy (outbound) |
|
||||
| matrix_synapse_workers_media | `0` | Amount of media-repo workers to deploy |
|
||||
| matrix_synapse_worker_push | `false` | Enables a worker for pushes to sygnal/emal |
|
||||
| matrix_synapse_worker_appservice | `false` | Enables a worker to handle synapse->appservice traffic |
|
||||
| matrix_synapse_worker_user_search | `false` | Enable a worker to handle user_directory search |
|
||||
| matrix_synapse_worker_replication_port | `9003` | Synapse replication port to use |
|
||||
| matrix_synapse_worker_metrics_enabled | `false` | Enable metrics endpoint on each worker |
|
||||
| matrix_synapse_worker_metrics_port | `9101` | Port on which metrics on each container can be reached |
|
||||
| Name | Default value | Description |
|
||||
| :--- | :--- | :--- |
|
||||
| `matrix_synapse_workers_enabled` | `false` | Enables workers and starts the replication listener |
|
||||
| `matrix_synapse_workers_client` | `0` | Amount of workers to deploy which serve the client API |
|
||||
| `matrix_synapse_workers_federation_in` | `0` | Amount of federation workers to deploy (inbound) |
|
||||
| `matrix_synapse_workers_federation_out` | `0` | Amount of federation sender workers to deploy (outbound) |
|
||||
| `matrix_synapse_workers_media` | `0` | Amount of media-repo workers to deploy |
|
||||
| `matrix_synapse_worker_push` | `false` | Enables a worker for pushes to sygnal/emal |
|
||||
| `matrix_synapse_worker_appservice` | `false` | Enables a worker to handle synapse->appservice traffic |
|
||||
| `matrix_synapse_worker_user_search` | `false` | Enable a worker to handle user_directory search |
|
||||
| `matrix_synapse_worker_replication_port` | `9003` | Synapse replication port to use |
|
||||
| `matrix_synapse_worker_metrics_enabled` | `false` | Enable metrics endpoint on each worker |
|
||||
| `matrix_synapse_worker_metrics_port` | `9101` | Port on which metrics on each container can be reached |
|
||||
|
||||
<a name="footnote_1">¹</a>: Docker must be used for both or neither deployment and supervision
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue