Add matrix-registration support

docs/configuring-playbook-matrix-registration.md

@@ -0,0 +1,53 @@
+# Setting up matrix-registration (optional)
+
+The playbook can install and configure [matrix-registration](https://github.com/ZerataX/matrix-registration) for you.
+
+> 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](#usage) below)
+
+- **a user registration page**, where people can use these registration tokens. By default, exposed at `https:///matrix.DOMAIN/matrix-registration`
+
+
+## Installing
+
+Adjust your playbook configuration (your `inventory/host_vars/matrix.DOMAIN/vars.yml` file):
+
+```yaml
+matrix_registration_enabled: true
+
+# Generate a strong secret using: `pwgen -s 64 1`.
+matrix_registration_admin_secret: "ENTER_SOME_SECRET_HERE"
+```
+
+Then, run the [installation](installing.md) command again:
+
+```
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
+```
+
+
+## Usage
+
+**matrix-registration** gets exposed at `https:///matrix.DOMAIN/matrix-registration`
+
+It provides various [APIs](https://github.com/ZerataX/matrix-registration/wiki/api) - 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 API (the one for creating unique registration tokens) easy to use via the playbook.
+
+**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.

docs/configuring-playbook.md

@@ -70,6 +70,8 @@ When you're done with all the configuration you'd like to do, continue with [Ins
 
 - [Setting up Synapse Admin](configuring-playbook-synapse-admin.md) (optional)
 
+- [Setting up matrix-registration](configuring-playbook-matrix-registration.md) (optional)
+
 - [Setting up the REST authentication password provider module](configuring-playbook-rest-auth.md) (optional, advanced)
 
 - [Setting up the Shared Secret Auth password provider module](configuring-playbook-shared-secret-auth.md) (optional, advanced)

docs/registering-users.md

@@ -1,6 +1,18 @@
 # Registering users
 
-Run this to create a new user account on your Matrix server.
+This documentation page tells you how to create user account on your Matrix server.
+
+Table of contents:
+
+- [Registering users](#registering-users)
+	- [Registering users manually](#registering-users-manually)
+	- [Managing users via a Web UI](#managing-users-via-a-web-ui)
+	- [Letting certain users register on your private server](#letting-certain-users-register-on-your-private-server)
+	- [Enabling public user registration](#enabling-public-user-registration)
+	- [Adding/Removing Administrator privileges to an existing user](#addingremoving-administrator-privileges-to-an-existing-user)
+
+
+## Registering users manually
 
 You can do it via this Ansible playbook (make sure to edit the `<your-username>` and `<your-password>` part below):
 
@@ -22,10 +34,29 @@ ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=<your-usern
 
 If you've just installed Matrix, **to finalize the installation process**, it's best if you proceed to [Configuring service discovery via .well-known](configuring-well-known.md)
 
------
+
+## Managing users via a Web UI
+
+To manage users more easily (via a web user-interace), you can install [Synapse Admin](configuring-playbook-synapse-admin.md).
 
 
-## Adding/Removing Administrator privileges to an existing user.
+## Letting certain users register on your private server
+
+If you'd rather **keep your server private** (public registration closed, as is the default), and **let certain people create accounts by themselves** (instead of creating user accounts manually like this), consider installing and making use of [matrix-registration](configuring-playbook-matrix-registration.md).
+
+
+## Enabling public user registration
+
+To **open up user registration publicly** (usually **not recommended**), consider using the following configuration:
+
+```yaml
+matrix_synapse_enable_registration: true
+```
+
+and running the [installation](installing.md) procedure once again.
+
+
+## Adding/Removing Administrator privileges to an existing user
 
 The script `/usr/local/bin/matrix-change-user-admin-status` may be used to change a user's admin privileges.
 
@@ -35,8 +66,3 @@ The script `/usr/local/bin/matrix-change-user-admin-status` may be used to chang
 ```
 /usr/local/bin/matrix-change-user-admin-status <username> <0/1>
 ```
-
-
-## Managing users via a Web UI
-
-To manage users more easily (via a web user-interace), you can install [Synapse Admin](configuring-playbook-synapse-admin.md).

docs/self-building.md

@@ -13,6 +13,7 @@ List of roles where self-building the Docker image is currently possible:
 - `matrix-synapse`
 - `matrix-synapse-admin`
 - `matrix-client-element`
+- `matrix-registration`
 - `matrix-coturn`
 - `matrix-ma1sd`
 - `matrix-mailer`