matrix-docker-ansible-deploy/docs/configuring-playbook-matrix-registration.md

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 curl or 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

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"

Installing

After configuring the playbook, 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