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

Setting up matrix-registration (optional)

⚠️ Warnings:

• This is a poorly maintained and buggy project. It's better to avoid using it.
• This is not related to matrix-registration-bot

The playbook can install and configure matrix-registration for you. It 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 certain people (these having a special link) to register a user account, keeping your server's registration closed (private).

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

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. You can create one with a command like `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 playbook with playbook tags as below:

ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start

The shortcut commands with the just program are also available: just install-all or just setup-all

just install-all is useful for maintaining your setup quickly (2x-5x faster than just setup-all) when its components remain unchanged. If you adjust your vars.yml to remove other components, you'd need to run just setup-all, or these components will still remain installed. Note these shortcuts run the ensure-matrix-users-created tag too.

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

The shortcut command with just program is also available: just run-tags list-matrix-registration-tokens