3.9 KiB
Setting up matrix-registration (optional)
The playbook can install and configure matrix-registration for you.
WARNING: this is a poorly maintained and buggy project. It's better to avoid using it.
WARNING: this is not related to matrix-registration-bot
matrix-registration is a simple python application to have a token based Matrix registration.
Use matrix-registration to create unique registration links, which people can use to register on your Matrix server. It allows you to keep your server's registration closed (private), but still allow certain people (these having a special link) to register a user account.
matrix-registration provides 2 things:
-
an API for creating registration tokens (unique registration links). This API can be used via
curlor via the playbook (see Usage below) -
a user registration page, where people can use these registration tokens. By default, exposed at
https://matrix.example.com/matrix-registration
Adjusting the playbook configuration
To enable matrix-registration, add the following configuration to your inventory/host_vars/matrix.example.com/vars.yml file:
matrix_registration_enabled: true
# Generate a strong secret here. Consider generating it with `pwgen -s 64 1`
matrix_registration_admin_secret: "ENTER_SOME_SECRET_HERE"
Adjusting the matrix-registration URL
By default, this playbook installs the matrix-registration on the matrix. subdomain, at the /matrix-registration path (https://matrix.example.com/matrix-registration). This makes it easy to install it, because it doesn't require additional DNS records to be set up. If that's okay, you can skip this section.
By tweaking the matrix_registration_hostname and matrix_registration_path_prefix variables, you can easily make the service available at a different hostname and/or path than the default one.
Example additional configuration for your inventory/host_vars/matrix.example.com/vars.yml file:
# Change the default hostname and path prefix
matrix_registration_hostname: registration.example.com
matrix_registration_path_prefix: /
Adjusting DNS records
If you've changed the default hostname, you may need to adjust your DNS records to point the matrix-registration domain to the Matrix server.
See Configuring DNS for details about DNS changes.
If you've decided to use the default hostname, you won't need to do any extra DNS configuration.
Installing
After configuring the playbook and potentially adjusting your DNS records, run the installation command:
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
Usage
matrix-registration gets exposed at https://matrix.example.com/matrix-registration
It provides various APIs - for creating registration tokens, listing tokens, disabling tokens, etc. To make use of all of its capabilities, consider using curl.
We make the most common APIs easy to use via the playbook (see below).
Creating registration tokens
To create a new user registration token (link), use this command:
ansible-playbook -i inventory/hosts setup.yml \
--tags=generate-matrix-registration-token \
--extra-vars="one_time=yes ex_date=2021-12-31"
The above command creates and returns a one-time use token, which expires on the 31st of December 2021.
Adjust the one_time and ex_date variables as you see fit.
Share the unique registration link (generated by the command above) with users to let them register on your Matrix server.
Listing registration tokens
To list the existing user registration tokens, use this command:
ansible-playbook -i inventory/hosts setup.yml \
--tags=list-matrix-registration-tokens