From fb3745a7b28cf232d4412f003265971b44253a2e Mon Sep 17 00:00:00 2001 From: Slavi Pantaleev Date: Sat, 22 Jun 2024 14:40:35 +0300 Subject: [PATCH] Update maubot docs (explicit password, other clarification) --- docs/configuring-playbook-bot-maubot.md | 37 +++++++++---------------- 1 file changed, 13 insertions(+), 24 deletions(-) diff --git a/docs/configuring-playbook-bot-maubot.md b/docs/configuring-playbook-bot-maubot.md index a8c6dcb61..d2b7dbc27 100644 --- a/docs/configuring-playbook-bot-maubot.md +++ b/docs/configuring-playbook-bot-maubot.md @@ -14,26 +14,26 @@ Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars. ```yaml matrix_bot_maubot_enabled: true + +# Uncomment and adjust this part if you'd like to use a username different than the default +# matrix_bot_maubot_login: bot.maubot + +# Generate a strong password here. Consider generating it with `pwgen -s 64 1` +matrix_bot_maubot_initial_password: PASSWORD_FOR_THE_BOT + matrix_bot_maubot_admins: - yourusername: securepassword ``` -You can add multiple admins. The admin accounts are not connected to any matrix ID and are only used to access the -maubot administration interface. +You can add multiple admins. The admin accounts are only used to access the maubot administration interface. ## Installing -After configuring the playbook, run the [installation](installing.md) command again: - -``` -ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start -``` +After configuring the playbook, run the [installation](installing.md) command again (`just install-all`): **Notes**: -- the `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account - - if you change the bot password (`matrix_bot_maubot_initial_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 [synapse-admin](configuring-playbook-synapse-admin.md) to change it. @@ -43,24 +43,13 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use You can visit `matrix./_matrix/maubot/` to manage your available plugins, clients and instances. You should start in the following order -1. **Create one or more clients:** A client is a matrix account which the bot will use to message. +1. **Create one or more clients:** A client is a matrix account which the bot will use to message. By default, the playbook creates a `bot.maubot` account (as per the configuration above). You only need to [obtain an access token](#obtaining-an-access-token) for it 2. **Upload some Plugins:** Plugins can be obtained from [here](https://github.com/maubot/maubot#plugins) or any other source. 3. **Create an instance:** An instance is the actual bot. You have to specify a client which the bot instance will use and the plugin (how the bot will behave) -To add a client you first need to create an account and obtain a valid access token. +## Obtaining an access token -## Registering the bot user +This can be done via `mbc login` then `mbc auth` (see the [maubot documentation](https://docs.mau.fi/maubot/usage/cli/auth.html)). To run these commands, you'll first need to `exec` into the maubot container with `docker exec -it matrix-bot-maubot sh`. -You **need to register the bot user manually** before setting up the bot. You can use the playbook to [register a new user](registering-users.md): - -``` -ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.maubot password=PASSWORD_FOR_THE_BOT admin=yes' --tags=register-user -``` - -Choose a strong password for the bot. You can generate a good password with a command like this: `pwgen -s 64 1`. - -## Obtaining an admin access token - -This can be done via `mbc login` then `mbc auth` (see the [maubot documentation](https://docs.mau.fi/maubot/usage/cli/auth.html)). To run these commands you'll need to open the bot docker container with `docker exec -it matrix-bot-maubot sh` -Alternatively, use Element or curl to [obtain an access token](obtaining-access-tokens.md). +Alternatively, you can follow our generic [obtain an access token](obtaining-access-tokens.md) documentation.