From fb3745a7b28cf232d4412f003265971b44253a2e Mon Sep 17 00:00:00 2001
From: Slavi Pantaleev <slavi@devture.com>
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.<your-domain>/_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.