This documentation is out of date!

This documentation site is for the versions of matrix-authentication-service maintained by the Matrix.org Foundation (github.com/matrix-org/matrix-authentication-service), available under the Apache 2.0 licence.

Since version 0.12.0, matrix-authentication-service is now maintained by Element under a new licence (github.com/element-hq/matrix-authentication-service).

If you are interested in the documentation for a later version of matrix-authentication-service, please refer to https://element-hq.github.io/matrix-authentication-service/.

Database configuration

The service uses a PostgreSQL database to store all of its state. Although it may be possible to run with earlier versions, it is recommended to use PostgreSQL 13 or later. Connection to the database is configured in the database section of the configuration file.

Set up a database

You will need to create a dedicated PostgreSQL database for the service. The database can run on the same server as the service, or on a dedicated host. The recommended setup for this database is to create a dedicated role and database for the service.

Assuming your PostgreSQL database user is called postgres, first authenticate as the database user with:

su - postgres
# Or, if your system uses sudo to get administrative rights
sudo -u postgres bash

Then, create a postgres user and a database with:

# this will prompt for a password for the new user
createuser --pwprompt mas_user
createdb --owner=mas_user mas

The above will create a user called mas_user with a password of your choice, and a database called mas owned by the mas_user user.

Service configuration

Once the database is created, the service needs to be configured to connect to it. Edit the database section of the configuration file to match the database just created:

database:
  # Full connection string as per
  # https://www.postgresql.org/docs/13/libpq-connect.html#id-1.7.3.8.3.6
  uri: postgres://<user>:<password>@<host>/<database>

  # -- OR --
  # Separate parameters
  host: <host>
  port: 5432
  username: <user>
  password: <password>
  database: <database>

Database migrations

The service manages the database schema with embedded migrations. Those migrations are run automatically when the service starts, but it is also possible to run them manually. This is done using the database migrate command:

mas-cli database migrate

Next steps

Once the database is up, the remaining steps are to: