73 lines
3.2 KiB
Markdown
73 lines
3.2 KiB
Markdown
# Setting up matrix-registration-bot (optional)
|
|
|
|
The playbook can install and configure [matrix-registration-bot](https://github.com/moan0s/matrix-registration-bot) for you.
|
|
|
|
The bot allows you to easily **create and manage registration tokens**. It can be used for an invitation-based server,
|
|
where you invite someone by sending them a registration token. They can register as normal but have to provide a valid
|
|
registration token in a final step of the registration.
|
|
|
|
See the project's [documentation](https://github.com/moan0s/matrix-registration-bot#supported-commands) to learn what it
|
|
does and why it might be useful to you.
|
|
|
|
|
|
## Registering the bot user
|
|
|
|
By default, the playbook will set use the bot with a username like this: `@bot.matrix-registration-bot:DOMAIN`.
|
|
|
|
(to use a different username, adjust the `matrix_bot_matrix_registration_bot_matrix_user_id_localpart` variable).
|
|
|
|
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.matrix-registration-bot 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
|
|
|
|
In order to use the bot you need to add an admin user's access token token to the configuration. As you created an admin user for the
|
|
bot, it is recommended to obtain an access token by logging into Element/Schildichat with the bot account
|
|
(using the password you set) and navigate to `Settings->Help&About` and scroll to the bottom.
|
|
You can expand "Access token" to copy it.
|
|
|
|
|
|
|
|
**IMPORTANT**: once you copy the token, just close the Matrix client window/tab. Do not "log out", as that would invalidate the token.
|
|
|
|
## Adjusting the playbook configuration
|
|
|
|
Add the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
|
|
|
|
```yaml
|
|
matrix_bot_matrix_registration_bot_enabled: true
|
|
# Token obtained via logging into the bot account (see above)
|
|
matrix_bot_matrix_registration_bot_bot_access_token: "syt_bW9hbm9z_XXXXXXXXXXXXXr_2kuzbE"
|
|
|
|
# Enables registration
|
|
matrix_synapse_enable_registration: true
|
|
|
|
# Restrict registration to users with a token
|
|
matrix_synapse_registration_requires_token: true
|
|
```
|
|
|
|
|
|
## Installing
|
|
|
|
After configuring the playbook, run the [installation](installing.md) command again:
|
|
|
|
```
|
|
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
|
|
```
|
|
|
|
|
|
## Usage
|
|
|
|
To use the bot, create a **non-encrypted** room and invite `@bot.matrix-registration-bot:DOMAIN` (where `YOUR_DOMAIN` is your base domain, not the `matrix.` domain).
|
|
|
|
In this room send `help` and the bot will reply with all options.
|
|
|
|
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 [troublshooting 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).
|