From 43cce09a1b1a7ccf1b4744438095fa5bb163130c Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Mon, 1 Jun 2026 14:59:04 -0400 Subject: [PATCH] Update docs Signed-off-by: Suguru Hirahara --- README.md | 1 - ...ng-playbook-bot-matrix-registration-bot.md | 107 ++++-------------- docs/configuring-playbook.md | 4 +- docs/container-images.md | 2 +- 4 files changed, 22 insertions(+), 92 deletions(-) diff --git a/README.md b/README.md index 5adf9c26d..c2932e58f 100644 --- a/README.md +++ b/README.md @@ -144,7 +144,6 @@ Bots provide various additional functionality to your installation. | ---- | -------- | ----------- | ------------- | | [baibot](https://github.com/etkecc/baibot) | ❌ | Bot that exposes the power of [AI](https://en.wikipedia.org/wiki/Artificial_intelligence) / [Large Language Models](https://en.wikipedia.org/wiki/Large_language_model) to you | [Link](docs/configuring-playbook-bot-baibot.md) | | [matrix-reminder-bot](https://github.com/anoadragon453/matrix-reminder-bot) | ❌ | Bot for scheduling one-off & recurring reminders and alarms | [Link](docs/configuring-playbook-bot-matrix-reminder-bot.md) | -| [matrix-registration-bot](https://github.com/moan0s/matrix-registration-bot) | ❌ | Bot for invitations by creating and managing registration tokens | [Link](docs/configuring-playbook-bot-matrix-registration-bot.md) | | [maubot](https://github.com/maubot/maubot) | ❌ | Plugin-based Matrix bot system | [Link](docs/configuring-playbook-bot-maubot.md) | | [Honoroit](https://github.com/etkecc/honoroit) | ❌ | Helpdesk bot | [Link](docs/configuring-playbook-bot-honoroit.md) | | [Mjolnir](https://github.com/matrix-org/mjolnir) | ❌ | Moderation tool for Matrix | [Link](docs/configuring-playbook-bot-mjolnir.md) | diff --git a/docs/configuring-playbook-bot-matrix-registration-bot.md b/docs/configuring-playbook-bot-matrix-registration-bot.md index 6563190b3..d1c96587d 100644 --- a/docs/configuring-playbook-bot-matrix-registration-bot.md +++ b/docs/configuring-playbook-bot-matrix-registration-bot.md @@ -1,103 +1,34 @@ -# Setting up matrix-registration-bot (optional) +# Setting up matrix-registration-bot (optional, removed) -The playbook can install and configure [matrix-registration-bot](https://github.com/moan0s/matrix-registration-bot) for you. +🪦 The playbook used to be able to install and configure [matrix-registration-bot](https://github.com/moan0s/matrix-registration-bot), but no longer includes this component, as it has been unmaintained. -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 (tokens look like this: `rbalQ0zkaDSRQCOp`). They can register as per normal but have to provide a valid registration token in the final step of the registration process. +## Uninstalling the component manually -See the project's [documentation](https://github.com/moan0s/matrix-registration-bot/blob/master/README.md) to learn what it does and why it might be useful to you. +If you still have matrix-registration-bot installed on your Matrix server, the playbook can no longer help you uninstall it and you will need to do it manually. To uninstall manually, run these commands on the server: -## Adjusting the playbook configuration - -To enable the bot, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: - -```yaml -matrix_bot_matrix_registration_bot_enabled: true - -# By default, the playbook will set use the bot with a username like this: `@bot.matrix-registration-bot:example.com`. -# Uncomment and adjust this part if you'd like to use a username different than the default -# matrix_bot_matrix_registration_bot_matrix_user_id_localpart: bot.matrix-registration-bot - -# Generate a strong password for the bot. You can create one with a command like `pwgen -s 64 1`. -matrix_bot_matrix_registration_bot_bot_password: PASSWORD_FOR_THE_BOT - -# Enables registration -matrix_synapse_enable_registration: true - -# Restrict registration to users with a token -matrix_synapse_registration_requires_token: true - -# Set an optional command prefix for the bot. This can be any arbitrary string, including whitespace. -# Example: "!regbot " -matrix_bot_matrix_registration_bot_bot_prefix: "" -``` - -The bot account will be created automatically. - -### Extending the configuration - -There are some additional things you may wish to configure about the bot. - -Take a look at: - -- `roles/custom/matrix-bot-matrix-registration-bot/defaults/main.yml` for some variables that you can customize via your `vars.yml` file -- `roles/custom/matrix-bot-matrix-registration-bot/templates/config.yaml.j2` for the bridge's default configuration - -## Installing - -After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below: - - ```sh -ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start -``` - -**Notes**: - -- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account. - -- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all` - - `just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) 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. - -- If you change the bot password (`matrix_bot_matrix_registration_bot_bot_password` in your `vars.yml` file) subsequently, the bot user's credentials on the homeserver won't be updated automatically. If you'd like to change the bot user's password, use a tool like [Ketesa](configuring-playbook-ketesa.md) to change it, and then update `matrix_bot_matrix_registration_bot_bot_password` to let the bot know its new password. - -## Usage - -To use the bot, start a chat with `@bot.matrix-registration-bot:example.com` (where `example.com` is your base domain, not the `matrix.` domain). - -Send `help` to the bot to see the available commands. - -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 [troubleshooting 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). - -To clean the cache (session & encryption data) after you changed the bot's username, changed the login method from access_token to password etc… you can use: - -```sh -just run-tags bot-matrix-registration-bot-clean-cache -``` - -## Troubleshooting - -As with all other services, you can find the logs in [systemd-journald](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) by logging in to the server with SSH and running `journalctl -fu matrix-bot-matrix-registration-bot`. - -### Increase logging verbosity - -The default logging level for this component is `INFO`. If you want to increase the verbosity, add the following configuration to your `vars.yml` file and re-run the playbook: +systemctl disable --now matrix-bot-matrix-registration-bot.service -```yaml -# Valid values: ERROR, INFO, DEBUG -matrix_bot_matrix_registration_bot_logging_level: DEBUG +rm -rf /matrix/matrix-registration-bot ``` diff --git a/docs/configuring-playbook.md b/docs/configuring-playbook.md index 9593fd46b..b5e79a531 100644 --- a/docs/configuring-playbook.md +++ b/docs/configuring-playbook.md @@ -192,8 +192,6 @@ Bots provide various additional functionality to your installation. - [Setting up matrix-reminder-bot](configuring-playbook-bot-matrix-reminder-bot.md) — a bot to remind you about stuff -- [Setting up matrix-registration-bot](configuring-playbook-bot-matrix-registration-bot.md) — a bot to create and manage registration tokens to invite users - - [Setting up maubot](configuring-playbook-bot-maubot.md) — a plugin-based Matrix bot system - [Setting up Honoroit](configuring-playbook-bot-honoroit.md) — a helpdesk bot @@ -281,6 +279,8 @@ Various services that don't fit any other categories. - [Setting up matrix-registration](configuring-playbook-matrix-registration.md) (removed; this component has been unmaintained) +- [Setting up matrix-registration-bot](configuring-playbook-bot-matrix-registration-bot.md) (removed; this component has been unmaintained) + - [Setting up Mautrix Facebook bridging](configuring-playbook-bridge-mautrix-facebook.md) (deprecated in favor of the Messenger/Instagram bridge with [mautrix-meta-messenger](configuring-playbook-bridge-mautrix-meta-messenger.md)) - [Setting up Mautrix Instagram bridging](configuring-playbook-bridge-mautrix-instagram.md) (deprecated in favor of the Messenger/Instagram bridge with [mautrix-meta-instagram](configuring-playbook-bridge-mautrix-meta-instagram.md)) diff --git a/docs/container-images.md b/docs/container-images.md index 7e1c5dc16..a28c6bf10 100644 --- a/docs/container-images.md +++ b/docs/container-images.md @@ -118,7 +118,6 @@ Bots provide various additional functionality to your installation. | ------- | --------------- | -------- | ----------- | | [baibot](configuring-playbook-bot-baibot.md) | [etke.cc/baibot](https://ghcr.io/etkecc/baibot) | ❌ | Bot that exposes the power of [AI](https://en.wikipedia.org/wiki/Artificial_intelligence) / [Large Language Models](https://en.wikipedia.org/wiki/Large_language_model) to you | | [matrix-reminder-bot](configuring-playbook-bot-matrix-reminder-bot.md) | [anoa/matrix-reminder-bot](https://hub.docker.com/r/anoa/matrix-reminder-bot) | ❌ | Bot for scheduling one-off & recurring reminders and alarms | -| [matrix-registration-bot](configuring-playbook-bot-matrix-registration-bot.md) | [moanos/matrix-registration-bot](https://hub.docker.com/r/moanos/matrix-registration-bot/) | ❌ | Bot for invitations by creating and managing registration tokens | | [maubot](configuring-playbook-bot-maubot.md) | [dock.mau.dev/maubot/maubot](https://mau.dev/maubot/maubot/container_registry) | ❌ | Plugin-based Matrix bot system | | [Honoroit](configuring-playbook-bot-honoroit.md) | [etke.cc/honoroit](https://github.com/etkecc/honoroit/container_registry) | ❌ | Helpdesk bot | | [Mjolnir](configuring-playbook-bot-mjolnir.md) | [matrixdotorg/mjolnir](https://hub.docker.com/r/matrixdotorg/mjolnir) | ❌ | Moderation tool for Matrix | @@ -179,6 +178,7 @@ The list of the deprecated or unmaintained services is available [here](configur | [matrix-chatgpt-bot](configuring-playbook-bot-chatgpt.md) | [matrixgpt/matrix-chatgpt-bot](https://ghcr.io/matrixgpt/matrix-chatgpt-bot) | ❌ | Accessing ChatGPT via your favourite Matrix client | | [matrix-ldap-registration-proxy](configuring-playbook-matrix-ldap-registration-proxy.md) | [activism.international/matrix_ldap_registration_proxy](https://gitlab.com/activism.international/matrix_ldap_registration_proxy/container_registry) | ❌ | Proxy that handles Matrix registration requests and forwards them to LDAP | | [matrix-registration](configuring-playbook-matrix-registration.md) | [zeratax/matrix-registration](https://hub.docker.com/r/devture/zeratax-matrix-registration/) | ❌ | Simple python application to have a token based Matrix registration | +| [matrix-registration-bot](configuring-playbook-bot-matrix-registration-bot.md) | [moanos/matrix-registration-bot](https://hub.docker.com/r/moanos/matrix-registration-bot/) | ❌ | Bot for invitations by creating and managing registration tokens | | [mautrix-facebook](configuring-playbook-bridge-mautrix-facebook.md) | [mautrix/facebook](https://mau.dev/mautrix/facebook/container_registry) | ❌ | Bridge to [Facebook](https://facebook.com/) | | [mautrix-instagram](configuring-playbook-bridge-mautrix-instagram.md) | [mautrix/instagram](https://mau.dev/mautrix/instagram/container_registry) | ❌ | Bridge to [Instagram](https://instagram.com/) | | [mx-puppet-discord](configuring-playbook-bridge-mx-puppet-discord.md) | [mx-puppet/discord/mx-puppet-discord](https://gitlab.com/mx-puppet/discord/mx-puppet-discord/container_registry) | ❌ | Bridge to [Discord](https://discordapp.com/) |