| @@ -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. | |||
| ## Registering the bot user | |||
| 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 access token | |||
| ## 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 first need to `exec` into the maubot container with `docker exec -it matrix-bot-maubot sh`. | |||
| 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. | |||