finallycoffee/matrix-docker-ansible-deploy
finallycoffee/matrix-docker-ansible-deploy
5
1
Fork 0
Code Issues Pull Requests Releases Wiki Activity
bf95ad2235
matrix-docker-ansible-deploy/docs/configuring-playbook-bot-matrix-registration-bot.md

52 lines
2.3 KiB
Markdown
Raw Normal View History

Add matrix-registration-bot (#1771) * Add matrix-registration-bot This adds an install and uninstall task plus helpers. The bot is disabled by default. This commit does not include documentation, yet. In short, the bot can be enabled by adding matrix_bot_matrix_registration_bot_enabled: true matrix_bot_matrix_registration_bot_matrix_user_password: "verysecret" matrix_bot_matrix_registration_bot_matrix_admin_token: "supersecret" to the host_vars * Change bot username to bot.matrix-registration-bot following convention * Address smaller remarks, fix local docker build * Switch to an env file * Add environment variables extension for additional config * Add documentation for the matrix-registration-bot * Add screenshot on how to obtain admin access token * Use bot as admin to only have one access token (bot and admin api) * Use cleaner setting of matrix_synapse_registration_requires_token * Use config file for cleaner more secure usage * Delete unneeded env * Rename vars to make usage clear * Fix typos/wording and add notice about logging out * Convert configuration to use |to_json * Reorder role includes Nothing should be after `matrix-common-after`. `matrix-bot-matrix-registration-bot` can probably be anywhere, but it makes sense to put it next to the other `matrix-bot-*` roles. * Minor group_vars/matrix_servers touchups Co-authored-by: Slavi Pantaleev <slavi@devture.com>
2022-04-21 08:07:47 +00:00
# Setting up matrix-registration-bot (optional)
Fix matrix-registration-bot repository URL
2022-04-21 08:21:29 +00:00
The playbook can install and configure [matrix-registration-bot](https://github.com/moan0s/matrix-registration-bot) for you.
Add matrix-registration-bot (#1771) * Add matrix-registration-bot This adds an install and uninstall task plus helpers. The bot is disabled by default. This commit does not include documentation, yet. In short, the bot can be enabled by adding matrix_bot_matrix_registration_bot_enabled: true matrix_bot_matrix_registration_bot_matrix_user_password: "verysecret" matrix_bot_matrix_registration_bot_matrix_admin_token: "supersecret" to the host_vars * Change bot username to bot.matrix-registration-bot following convention * Address smaller remarks, fix local docker build * Switch to an env file * Add environment variables extension for additional config * Add documentation for the matrix-registration-bot * Add screenshot on how to obtain admin access token * Use bot as admin to only have one access token (bot and admin api) * Use cleaner setting of matrix_synapse_registration_requires_token * Use config file for cleaner more secure usage * Delete unneeded env * Rename vars to make usage clear * Fix typos/wording and add notice about logging out * Convert configuration to use |to_json * Reorder role includes Nothing should be after `matrix-common-after`. `matrix-bot-matrix-registration-bot` can probably be anywhere, but it makes sense to put it next to the other `matrix-bot-*` roles. * Minor group_vars/matrix_servers touchups Co-authored-by: Slavi Pantaleev <slavi@devture.com>
2022-04-21 08:07:47 +00:00
Update matrix-registration-bot, improve authentication config (#2723) * Adjust to new mrb docker versioning * Stabilze authentication * fix lint * Move & document mrb password usage * Add clean cache role * Document clean cache * Fix lint * Update CHANGELOG.md * Automate access tokens * Improve changelog * Make use of mrb's function to fetch API tokens * Adjust changelog * Use ansible.builtin.file to clear directory * Fix typo --------- Co-authored-by: Slavi Pantaleev <slavi@devture.com>
2023-07-24 10:57:06 +00:00
The bot allows you to easily **create and manage registration tokens** aka. invitation codes.
It can be used for an invitation-based server,
where you invite someone by sending them a registration token (loook like this: `rbalQ0zkaDSRQCOp`). They can register as normal but have to provide a valid registration token in a final step of the registration.
Add matrix-registration-bot (#1771) * Add matrix-registration-bot This adds an install and uninstall task plus helpers. The bot is disabled by default. This commit does not include documentation, yet. In short, the bot can be enabled by adding matrix_bot_matrix_registration_bot_enabled: true matrix_bot_matrix_registration_bot_matrix_user_password: "verysecret" matrix_bot_matrix_registration_bot_matrix_admin_token: "supersecret" to the host_vars * Change bot username to bot.matrix-registration-bot following convention * Address smaller remarks, fix local docker build * Switch to an env file * Add environment variables extension for additional config * Add documentation for the matrix-registration-bot * Add screenshot on how to obtain admin access token * Use bot as admin to only have one access token (bot and admin api) * Use cleaner setting of matrix_synapse_registration_requires_token * Use config file for cleaner more secure usage * Delete unneeded env * Rename vars to make usage clear * Fix typos/wording and add notice about logging out * Convert configuration to use |to_json * Reorder role includes Nothing should be after `matrix-common-after`. `matrix-bot-matrix-registration-bot` can probably be anywhere, but it makes sense to put it next to the other `matrix-bot-*` roles. * Minor group_vars/matrix_servers touchups Co-authored-by: Slavi Pantaleev <slavi@devture.com>
2022-04-21 08:07:47 +00:00
See the project's [documentation](https://github.com/moan0s/matrix-registration-bot#supported-commands) to learn what it
does and why it might be useful to you.
Update matrix-registration-bot, improve authentication config (#2723) * Adjust to new mrb docker versioning * Stabilze authentication * fix lint * Move & document mrb password usage * Add clean cache role * Document clean cache * Fix lint * Update CHANGELOG.md * Automate access tokens * Improve changelog * Make use of mrb's function to fetch API tokens * Adjust changelog * Use ansible.builtin.file to clear directory * Fix typo --------- Co-authored-by: Slavi Pantaleev <slavi@devture.com>
2023-07-24 10:57:06 +00:00
## Configuration
Add matrix-registration-bot (#1771) * Add matrix-registration-bot This adds an install and uninstall task plus helpers. The bot is disabled by default. This commit does not include documentation, yet. In short, the bot can be enabled by adding matrix_bot_matrix_registration_bot_enabled: true matrix_bot_matrix_registration_bot_matrix_user_password: "verysecret" matrix_bot_matrix_registration_bot_matrix_admin_token: "supersecret" to the host_vars * Change bot username to bot.matrix-registration-bot following convention * Address smaller remarks, fix local docker build * Switch to an env file * Add environment variables extension for additional config * Add documentation for the matrix-registration-bot * Add screenshot on how to obtain admin access token * Use bot as admin to only have one access token (bot and admin api) * Use cleaner setting of matrix_synapse_registration_requires_token * Use config file for cleaner more secure usage * Delete unneeded env * Rename vars to make usage clear * Fix typos/wording and add notice about logging out * Convert configuration to use |to_json * Reorder role includes Nothing should be after `matrix-common-after`. `matrix-bot-matrix-registration-bot` can probably be anywhere, but it makes sense to put it next to the other `matrix-bot-*` roles. * Minor group_vars/matrix_servers touchups Co-authored-by: Slavi Pantaleev <slavi@devture.com>
2022-04-21 08:07:47 +00:00
Update matrix-registration-bot, improve authentication config (#2723) * Adjust to new mrb docker versioning * Stabilze authentication * fix lint * Move & document mrb password usage * Add clean cache role * Document clean cache * Fix lint * Update CHANGELOG.md * Automate access tokens * Improve changelog * Make use of mrb's function to fetch API tokens * Adjust changelog * Use ansible.builtin.file to clear directory * Fix typo --------- Co-authored-by: Slavi Pantaleev <slavi@devture.com>
2023-07-24 10:57:06 +00:00
To enable the bot, add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
Add matrix-registration-bot (#1771) * Add matrix-registration-bot This adds an install and uninstall task plus helpers. The bot is disabled by default. This commit does not include documentation, yet. In short, the bot can be enabled by adding matrix_bot_matrix_registration_bot_enabled: true matrix_bot_matrix_registration_bot_matrix_user_password: "verysecret" matrix_bot_matrix_registration_bot_matrix_admin_token: "supersecret" to the host_vars * Change bot username to bot.matrix-registration-bot following convention * Address smaller remarks, fix local docker build * Switch to an env file * Add environment variables extension for additional config * Add documentation for the matrix-registration-bot * Add screenshot on how to obtain admin access token * Use bot as admin to only have one access token (bot and admin api) * Use cleaner setting of matrix_synapse_registration_requires_token * Use config file for cleaner more secure usage * Delete unneeded env * Rename vars to make usage clear * Fix typos/wording and add notice about logging out * Convert configuration to use |to_json * Reorder role includes Nothing should be after `matrix-common-after`. `matrix-bot-matrix-registration-bot` can probably be anywhere, but it makes sense to put it next to the other `matrix-bot-*` roles. * Minor group_vars/matrix_servers touchups Co-authored-by: Slavi Pantaleev <slavi@devture.com>
2022-04-21 08:07:47 +00:00
```yaml
matrix_bot_matrix_registration_bot_enabled: true
Update matrix-registration-bot, improve authentication config (#2723) * Adjust to new mrb docker versioning * Stabilze authentication * fix lint * Move & document mrb password usage * Add clean cache role * Document clean cache * Fix lint * Update CHANGELOG.md * Automate access tokens * Improve changelog * Make use of mrb's function to fetch API tokens * Adjust changelog * Use ansible.builtin.file to clear directory * Fix typo --------- Co-authored-by: Slavi Pantaleev <slavi@devture.com>
2023-07-24 10:57:06 +00:00
Adjust matrix-registration-bot docs to tell people to perform a full installation Running just `setup-all,start` is not enough, because it doesn't run `ensure-matrix-users-created` and the bot account won't get created.
2024-01-09 08:16:51 +00:00
# By default, the playbook will set use the bot with a username like this: `@bot.matrix-registration-bot:DOMAIN`.
# To use a different username, uncomment & adjust the variable below:
Update matrix-registration-bot, improve authentication config (#2723) * Adjust to new mrb docker versioning * Stabilze authentication * fix lint * Move & document mrb password usage * Add clean cache role * Document clean cache * Fix lint * Update CHANGELOG.md * Automate access tokens * Improve changelog * Make use of mrb's function to fetch API tokens * Adjust changelog * Use ansible.builtin.file to clear directory * Fix typo --------- Co-authored-by: Slavi Pantaleev <slavi@devture.com>
2023-07-24 10:57:06 +00:00
# matrix_bot_matrix_registration_bot_matrix_user_id_localpart: bot.matrix-registration-bot
Add matrix-registration-bot (#1771) * Add matrix-registration-bot This adds an install and uninstall task plus helpers. The bot is disabled by default. This commit does not include documentation, yet. In short, the bot can be enabled by adding matrix_bot_matrix_registration_bot_enabled: true matrix_bot_matrix_registration_bot_matrix_user_password: "verysecret" matrix_bot_matrix_registration_bot_matrix_admin_token: "supersecret" to the host_vars * Change bot username to bot.matrix-registration-bot following convention * Address smaller remarks, fix local docker build * Switch to an env file * Add environment variables extension for additional config * Add documentation for the matrix-registration-bot * Add screenshot on how to obtain admin access token * Use bot as admin to only have one access token (bot and admin api) * Use cleaner setting of matrix_synapse_registration_requires_token * Use config file for cleaner more secure usage * Delete unneeded env * Rename vars to make usage clear * Fix typos/wording and add notice about logging out * Convert configuration to use |to_json * Reorder role includes Nothing should be after `matrix-common-after`. `matrix-bot-matrix-registration-bot` can probably be anywhere, but it makes sense to put it next to the other `matrix-bot-*` roles. * Minor group_vars/matrix_servers touchups Co-authored-by: Slavi Pantaleev <slavi@devture.com>
2022-04-21 08:07:47 +00:00
# Enables registration
matrix_synapse_enable_registration: true
# Restrict registration to users with a token
matrix_synapse_registration_requires_token: true
```
Auto-generate matrix_bot_matrix_registration_bot_bot_password via group vars
2024-01-09 08:19:41 +00:00
The bot's user account will be created automatically.
Add matrix-registration-bot (#1771) * Add matrix-registration-bot This adds an install and uninstall task plus helpers. The bot is disabled by default. This commit does not include documentation, yet. In short, the bot can be enabled by adding matrix_bot_matrix_registration_bot_enabled: true matrix_bot_matrix_registration_bot_matrix_user_password: "verysecret" matrix_bot_matrix_registration_bot_matrix_admin_token: "supersecret" to the host_vars * Change bot username to bot.matrix-registration-bot following convention * Address smaller remarks, fix local docker build * Switch to an env file * Add environment variables extension for additional config * Add documentation for the matrix-registration-bot * Add screenshot on how to obtain admin access token * Use bot as admin to only have one access token (bot and admin api) * Use cleaner setting of matrix_synapse_registration_requires_token * Use config file for cleaner more secure usage * Delete unneeded env * Rename vars to make usage clear * Fix typos/wording and add notice about logging out * Convert configuration to use |to_json * Reorder role includes Nothing should be after `matrix-common-after`. `matrix-bot-matrix-registration-bot` can probably be anywhere, but it makes sense to put it next to the other `matrix-bot-*` roles. * Minor group_vars/matrix_servers touchups Co-authored-by: Slavi Pantaleev <slavi@devture.com>
2022-04-21 08:07:47 +00:00
## Installing
Adjust matrix-registration-bot docs to tell people to perform a full installation Running just `setup-all,start` is not enough, because it doesn't run `ensure-matrix-users-created` and the bot account won't get created.
2024-01-09 08:16:51 +00:00
After configuring the playbook, re-run the [installation](installing.md) command again: `just install-all` or `just setup-all`
Add matrix-registration-bot (#1771) * Add matrix-registration-bot This adds an install and uninstall task plus helpers. The bot is disabled by default. This commit does not include documentation, yet. In short, the bot can be enabled by adding matrix_bot_matrix_registration_bot_enabled: true matrix_bot_matrix_registration_bot_matrix_user_password: "verysecret" matrix_bot_matrix_registration_bot_matrix_admin_token: "supersecret" to the host_vars * Change bot username to bot.matrix-registration-bot following convention * Address smaller remarks, fix local docker build * Switch to an env file * Add environment variables extension for additional config * Add documentation for the matrix-registration-bot * Add screenshot on how to obtain admin access token * Use bot as admin to only have one access token (bot and admin api) * Use cleaner setting of matrix_synapse_registration_requires_token * Use config file for cleaner more secure usage * Delete unneeded env * Rename vars to make usage clear * Fix typos/wording and add notice about logging out * Convert configuration to use |to_json * Reorder role includes Nothing should be after `matrix-common-after`. `matrix-bot-matrix-registration-bot` can probably be anywhere, but it makes sense to put it next to the other `matrix-bot-*` roles. * Minor group_vars/matrix_servers touchups Co-authored-by: Slavi Pantaleev <slavi@devture.com>
2022-04-21 08:07:47 +00:00
## Usage
Update matrix-registration-bot, improve authentication config (#2723) * Adjust to new mrb docker versioning * Stabilze authentication * fix lint * Move & document mrb password usage * Add clean cache role * Document clean cache * Fix lint * Update CHANGELOG.md * Automate access tokens * Improve changelog * Make use of mrb's function to fetch API tokens * Adjust changelog * Use ansible.builtin.file to clear directory * Fix typo --------- Co-authored-by: Slavi Pantaleev <slavi@devture.com>
2023-07-24 10:57:06 +00:00
To use the bot, message `@bot.matrix-registration-bot:DOMAIN` (where `DOMAIN` is your base domain, not the `matrix.` domain).
Add matrix-registration-bot (#1771) * Add matrix-registration-bot This adds an install and uninstall task plus helpers. The bot is disabled by default. This commit does not include documentation, yet. In short, the bot can be enabled by adding matrix_bot_matrix_registration_bot_enabled: true matrix_bot_matrix_registration_bot_matrix_user_password: "verysecret" matrix_bot_matrix_registration_bot_matrix_admin_token: "supersecret" to the host_vars * Change bot username to bot.matrix-registration-bot following convention * Address smaller remarks, fix local docker build * Switch to an env file * Add environment variables extension for additional config * Add documentation for the matrix-registration-bot * Add screenshot on how to obtain admin access token * Use bot as admin to only have one access token (bot and admin api) * Use cleaner setting of matrix_synapse_registration_requires_token * Use config file for cleaner more secure usage * Delete unneeded env * Rename vars to make usage clear * Fix typos/wording and add notice about logging out * Convert configuration to use |to_json * Reorder role includes Nothing should be after `matrix-common-after`. `matrix-bot-matrix-registration-bot` can probably be anywhere, but it makes sense to put it next to the other `matrix-bot-*` roles. * Minor group_vars/matrix_servers touchups Co-authored-by: Slavi Pantaleev <slavi@devture.com>
2022-04-21 08:07:47 +00:00
In this room send `help` and the bot will reply with all options.
You can also refer to the upstream [Usage documentation](https://github.com/moan0s/matrix-registration-bot#supported-commands).
If you have any questions, or if you need help setting it up, read the [troublshooting guide](https://github.com/moan0s/matrix-registration-bot/blob/main/docs/troubleshooting.md)
or join [#matrix-registration-bot:hyteck.de](https://matrix.to/#/#matrix-registration-bot:hyteck.de).
Update matrix-registration-bot, improve authentication config (#2723) * Adjust to new mrb docker versioning * Stabilze authentication * fix lint * Move & document mrb password usage * Add clean cache role * Document clean cache * Fix lint * Update CHANGELOG.md * Automate access tokens * Improve changelog * Make use of mrb's function to fetch API tokens * Adjust changelog * Use ansible.builtin.file to clear directory * Fix typo --------- Co-authored-by: Slavi Pantaleev <slavi@devture.com>
2023-07-24 10:57:06 +00:00
To clean the cache (session&encryption data) after you changed the bot's username, changed the login methon form access_token to password etc.. you can use
```bash
just run-tags bot-matrix-registration-bot-clean-cache
```
Reference in New Issue Copy Permalink