From 9a56aff933112c484136b43ab1923175ce96abf2 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Sun, 22 Dec 2024 23:44:48 +0900 Subject: [PATCH] Edit docs for bots: adopt the common format - Add "To use the bot" if it does not exist: adopt the format of the docs for bridges - Add "Prerequisites" section if an API key or user account is required - Use the common instruction for getting an access token - Replace "Get" with "Obtain" about getting keys or access tokens - Replace placeholders for access tokens on docs/configuring-playbook-bot-go.neb.md Signed-off-by: Suguru Hirahara --- ...figuring-playbook-alertmanager-receiver.md | 5 ++-- docs/configuring-playbook-bot-baibot.md | 2 +- docs/configuring-playbook-bot-buscarron.md | 2 +- docs/configuring-playbook-bot-chatgpt.md | 28 +++++++++---------- docs/configuring-playbook-bot-draupnir.md | 6 ++-- docs/configuring-playbook-bot-go-neb.md | 18 ++++++------ docs/configuring-playbook-bot-honoroit.md | 2 +- ...ng-playbook-bot-matrix-registration-bot.md | 2 +- ...guring-playbook-bot-matrix-reminder-bot.md | 2 +- docs/configuring-playbook-bot-maubot.md | 4 +-- docs/configuring-playbook-bot-mjolnir.md | 6 ++-- docs/configuring-playbook-email2matrix.md | 2 +- docs/howto-server-delegation.md | 2 +- 13 files changed, 40 insertions(+), 41 deletions(-) diff --git a/docs/configuring-playbook-alertmanager-receiver.md b/docs/configuring-playbook-alertmanager-receiver.md index 08aca3d54..c42747e99 100644 --- a/docs/configuring-playbook-alertmanager-receiver.md +++ b/docs/configuring-playbook-alertmanager-receiver.md @@ -22,7 +22,7 @@ You can use the playbook to [register a new user](registering-users.md): ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.alertmanager.receiver password=PASSWORD_FOR_THE_BOT admin=no' --tags=register-user ``` -### Get an access token +### Obtain an access token The bot requires an access token to be able to connect to your homeserver. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md). @@ -36,7 +36,7 @@ Then, log in as the bot using any Matrix client of your choosing, accept the roo ## Adjusting the playbook configuration -Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `ACCESS_TOKEN_HERE` with the one created [above](#get-an-access-token). +Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `ACCESS_TOKEN_HERE` with the one created [above](#obtain-an-access-token). ```yaml matrix_alertmanager_receiver_enabled: true @@ -44,7 +44,6 @@ matrix_alertmanager_receiver_enabled: true # Uncomment and adjust this part if you'd like to use a username different than the default # matrix_alertmanager_receiver_config_matrix_user_id_localpart: "bot.alertmanager.receiver" -# Specify the bot user's access token here. matrix_alertmanager_receiver_config_matrix_access_token: "ACCESS_TOKEN_HERE" # Optionally, configure some mappings (URL-friendly room name -> actual Matrix room ID). diff --git a/docs/configuring-playbook-bot-baibot.md b/docs/configuring-playbook-bot-baibot.md index b2d05308d..1a80546e0 100644 --- a/docs/configuring-playbook-bot-baibot.md +++ b/docs/configuring-playbook-bot-baibot.md @@ -30,7 +30,7 @@ Depending on your current `vars.yml` file and desired configuration, **you may r ### Base configuration -Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: +To enable the bot, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_bot_baibot_enabled: true diff --git a/docs/configuring-playbook-bot-buscarron.md b/docs/configuring-playbook-bot-buscarron.md index 3fa6b4a43..1ac73e7e3 100644 --- a/docs/configuring-playbook-bot-buscarron.md +++ b/docs/configuring-playbook-bot-buscarron.md @@ -6,7 +6,7 @@ Buscarron is bot that receives HTTP POST submissions of web forms and forwards t ## Adjusting the playbook configuration -To enable Buscarron, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: +To enable the bot, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_bot_buscarron_enabled: true diff --git a/docs/configuring-playbook-bot-chatgpt.md b/docs/configuring-playbook-bot-chatgpt.md index 659ae77bb..e3ff7a431 100644 --- a/docs/configuring-playbook-bot-chatgpt.md +++ b/docs/configuring-playbook-bot-chatgpt.md @@ -6,11 +6,15 @@ The playbook can install and configure [matrix-chatgpt-bot](https://github.com/m Talk to [ChatGPT](https://openai.com/blog/chatgpt/) via your favourite Matrix client! -## Register the bot account +## Prerequisites -The playbook does not automatically create users for you. The bot requires an access token to be able to connect to your homeserver. +### Obtain an OpenAI API key -You **need to register the bot user manually** before setting up the bot. +To use the bot, you'd need to obtain an API key from [https://platform.openai.com/account/api-keys](https://platform.openai.com/account/api-keys). + +### Register the bot account + +The playbook does not automatically create users for you. You **need to register the bot user manually** before setting up the bot. Generate a strong password for the bot. You can create one with a command like `pwgen -s 64 1`. @@ -20,37 +24,31 @@ You can use the playbook to [register a new user](registering-users.md): ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.chatgpt password=PASSWORD_FOR_THE_BOT admin=no' --tags=register-user ``` -## Get an access token and create encryption keys +### Obtain an access token and create encryption keys -Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md). +The bot requires an access token to be able to connect to your homeserver. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md). To make sure the bot can read encrypted messages, it will need an encryption key, just like any other new user. While obtaining the access token, follow the prompts to setup a backup key. More information can be found in the [Element documentation](https://element.io/help#encryption6). ## Adjusting the playbook configuration -Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs): +To enable the bot, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `API_KEY_HERE` with the API key retrieved [here](#obtain-an-openai-api-key) and `ACCESS_TOKEN_HERE` with the access token created [here](#obtain-an-access-token-and-create-encryption-keys), respectively. ```yaml matrix_bot_chatgpt_enabled: true -# Obtain a new API key from https://platform.openai.com/account/api-keys -matrix_bot_chatgpt_openai_api_key: '' +matrix_bot_chatgpt_openai_api_key: 'API_KEY_HERE' -# This is the default username +# Uncomment and adjust this part if you'd like to use a username different than the default # matrix_bot_chatgpt_matrix_bot_username_localpart: 'bot.chatgpt' -# Matrix access token (from bot user above) -# see: https://webapps.stackexchange.com/questions/131056/how-to-get-an-access-token-for-element-riot-matrix -matrix_bot_chatgpt_matrix_access_token: '' +matrix_bot_chatgpt_matrix_access_token: 'ACCESS_TOKEN_HERE' # Configuring the system promt used, needed if the bot is used for special tasks. # More information: https://github.com/mustvlad/ChatGPT-System-Prompts matrix_bot_chatgpt_matrix_bot_prompt_prefix: 'Instructions:\nYou are ChatGPT, a large language model trained by OpenAI.' - ``` -You will need to get tokens for ChatGPT. - ## Installing After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below: diff --git a/docs/configuring-playbook-bot-draupnir.md b/docs/configuring-playbook-bot-draupnir.md index f4ce3e759..288a8547c 100644 --- a/docs/configuring-playbook-bot-draupnir.md +++ b/docs/configuring-playbook-bot-draupnir.md @@ -24,7 +24,7 @@ ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.draupni If you would like Draupnir to be able to deactivate users, move aliases, shutdown rooms, show abuse reports (see [below](#abuse-reports)), etc then it must be a server admin so you need to change `admin=no` to `admin=yes` in the command above. -### Get an access token +### Obtain an access token The bot requires an access token to be able to connect to your homeserver. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md). @@ -64,7 +64,7 @@ Finally invite the `@bot.draupnir:example.com` account you created earlier into ## Adjusting the playbook configuration -Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `MANAGEMENT_ROOM_ID_HERE`. +To enable the bot, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `MANAGEMENT_ROOM_ID_HERE`. ```yaml # Enable Draupnir @@ -113,7 +113,7 @@ matrix_bot_draupnir_raw_homeserver_url: "{{ matrix_addons_homeserver_client_api_ When NOT using Pantalaimon, Draupnir does not log in by itself and you must give it an access token for its bot account. -Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `ACCESS_TOKEN_HERE` with the one created [above](#get-an-access-token). +Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `ACCESS_TOKEN_HERE` with the one created [above](#obtain-an-access-token). ```yaml matrix_bot_draupnir_access_token: "ACCESS_TOKEN_HERE" diff --git a/docs/configuring-playbook-bot-go-neb.md b/docs/configuring-playbook-bot-go-neb.md index 359f55d73..1c3118dfb 100644 --- a/docs/configuring-playbook-bot-go-neb.md +++ b/docs/configuring-playbook-bot-go-neb.md @@ -8,11 +8,11 @@ Go-NEB is a Matrix bot written in Go. It is the successor to Matrix-NEB, the ori See the project's [documentation](https://github.com/matrix-org/go-neb/blob/master/README.md) to learn what it does and why it might be useful to you. -## Registering the bot account +## Prerequisites -The playbook does not automatically create users for you. The bot requires at least 1 access token to be able to connect to your homeserver. +### Register the bot account -You **need to register the bot user manually** before setting up the bot. +The playbook does not automatically create users for you. You **need to register the bot user manually** before setting up the bot. Generate a strong password for the bot. You can create one with a command like `pwgen -s 64 1`. @@ -22,11 +22,13 @@ You can use the playbook to [register a new user](registering-users.md): ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.go-neb password=PASSWORD_FOR_THE_BOT admin=no' --tags=register-user ``` -Once the user is created you can [obtain an access token](obtaining-access-tokens.md). +### Obtain an access token + +The bot requires an access token to be able to connect to your homeserver. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md). ## Adjusting the playbook configuration -To enable Go-NEB, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: +To enable the bot, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `ACCESS_TOKEN_FOR_GONEB_HERE` and `ACCESS_TOKEN_FOR_ANOTHER_GONEB_HERE` with the ones created [above](#obtain-an-access-token). ```yaml matrix_bot_go_neb_enabled: true @@ -35,7 +37,7 @@ matrix_bot_go_neb_enabled: true # Use the access token you obtained in the step above. matrix_bot_go_neb_clients: - UserID: "@goneb:{{ matrix_domain }}" - AccessToken: "MDASDASJDIASDJASDAFGFRGER" + AccessToken: "ACCESS_TOKEN_FOR_GONEB_HERE" DeviceID: "DEVICE1" HomeserverURL: "{{ matrix_addons_homeserver_client_api_url }}" Sync: true @@ -44,7 +46,7 @@ matrix_bot_go_neb_clients: AcceptVerificationFromUsers: [":{{ matrix_domain }}"] - UserID: "@another_goneb:{{ matrix_domain }}" - AccessToken: "MDASDASJDIASDJASDAFGFRGER" + AccessToken: "ACCESS_TOKEN_FOR_ANOTHER_GONEB_HERE" DeviceID: "DEVICE2" HomeserverURL: "{{ matrix_addons_homeserver_client_api_url }}" Sync: false @@ -105,7 +107,7 @@ matrix_bot_go_neb_services: api_key: "AIzaSyA4FD39m9" cx: "AIASDFWSRRtrtr" -# Get a key via https://api.imgur.com/oauth2/addclient +# Obtain a key via https://api.imgur.com/oauth2/addclient # Select "oauth2 without callback url" - ID: "imgur_service" Type: "imgur" diff --git a/docs/configuring-playbook-bot-honoroit.md b/docs/configuring-playbook-bot-honoroit.md index d0e887563..be8c9acee 100644 --- a/docs/configuring-playbook-bot-honoroit.md +++ b/docs/configuring-playbook-bot-honoroit.md @@ -8,7 +8,7 @@ See the project's [documentation](https://github.com/etkecc/honoroit/blob/main/R ## Adjusting the playbook configuration -To enable Honoroit, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: +To enable the bot, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_bot_honoroit_enabled: true diff --git a/docs/configuring-playbook-bot-matrix-registration-bot.md b/docs/configuring-playbook-bot-matrix-registration-bot.md index 8eb1132e4..95b86163f 100644 --- a/docs/configuring-playbook-bot-matrix-registration-bot.md +++ b/docs/configuring-playbook-bot-matrix-registration-bot.md @@ -6,7 +6,7 @@ The bot allows you to easily **create and manage registration tokens** aka. invi 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. -## Configuration +## Adjusting the playbook configuration To enable the bot, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: diff --git a/docs/configuring-playbook-bot-matrix-reminder-bot.md b/docs/configuring-playbook-bot-matrix-reminder-bot.md index d2b53fc63..d82c3eae1 100644 --- a/docs/configuring-playbook-bot-matrix-reminder-bot.md +++ b/docs/configuring-playbook-bot-matrix-reminder-bot.md @@ -8,7 +8,7 @@ See the project's [documentation](https://github.com/anoadragon453/matrix-remind ## Adjusting the playbook configuration -Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: +To enable the bot, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_bot_matrix_reminder_bot_enabled: true diff --git a/docs/configuring-playbook-bot-maubot.md b/docs/configuring-playbook-bot-maubot.md index 400898d39..04eeb0cb8 100644 --- a/docs/configuring-playbook-bot-maubot.md +++ b/docs/configuring-playbook-bot-maubot.md @@ -8,7 +8,7 @@ See the project's [documentation](https://docs.mau.fi/maubot/usage/basic.html) t ## Adjusting the playbook configuration -To enable maubot, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: +To enable the bot, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file: ```yaml matrix_bot_maubot_enabled: true @@ -75,7 +75,7 @@ You should start in the following order 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) -## Obtaining an access token +## Obtain an 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`. diff --git a/docs/configuring-playbook-bot-mjolnir.md b/docs/configuring-playbook-bot-mjolnir.md index 59630ae01..53fd17784 100644 --- a/docs/configuring-playbook-bot-mjolnir.md +++ b/docs/configuring-playbook-bot-mjolnir.md @@ -20,7 +20,7 @@ ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.mjolnir If you would like Mjolnir to be able to deactivate users, move aliases, shutdown rooms, etc then it must be a server admin so you need to change `admin=no` to `admin=yes` in the command above. -### Get an access token +### Obtain an access token The bot requires an access token to be able to connect to your homeserver. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md). @@ -60,7 +60,7 @@ Finally invite the `@bot.mjolnir:example.com` account you created earlier into t ## Adjusting the playbook configuration -Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `MANAGEMENT_ROOM_ID_HERE`. +To enable the bot, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `MANAGEMENT_ROOM_ID_HERE`. ```yaml # Enable Mjolnir @@ -109,7 +109,7 @@ matrix_bot_mjolnir_raw_homeserver_url: "{{ matrix_addons_homeserver_client_api_u When NOT using Pantalaimon, Mjolnir does not log in by itself and you must give it an access token for its bot account. -Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `ACCESS_TOKEN_HERE` with the one created [above](#get-an-access-token). +Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `ACCESS_TOKEN_HERE` with the one created [above](#obtain-an-access-token). ```yaml matrix_bot_mjolnir_access_token: "ACCESS_TOKEN_HERE" diff --git a/docs/configuring-playbook-email2matrix.md b/docs/configuring-playbook-email2matrix.md index 45f928dc7..4ceda308f 100644 --- a/docs/configuring-playbook-email2matrix.md +++ b/docs/configuring-playbook-email2matrix.md @@ -38,7 +38,7 @@ Inviting additional people to the room is okay too. Take note of each room's room ID (different clients show the room ID in a different place). You'll need the room ID when [configuring the playbook](#adjusting-the-playbook-configuration) below. -### Obtaining an access token for the sender user +### Obtain an access token for the sender user In order for the sender user created above to be able to send messages to the room, we'll need to obtain an access token for it. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md). diff --git a/docs/howto-server-delegation.md b/docs/howto-server-delegation.md index ff41f3eb3..429e06982 100644 --- a/docs/howto-server-delegation.md +++ b/docs/howto-server-delegation.md @@ -51,7 +51,7 @@ To use DNS SRV record validation, you need to: For more details on how to configure the playbook to work with SRV delegation, take a look at this documentation: [Server Delegation via a DNS SRV record (advanced)](howto-srv-server-delegation.md) -### Obtaining certificates +### Obtain certificates How you can obtain a valid certificate for `example.com` on the `matrix.example.com` server is up to you.