authentication-service/docs/usage/installation.md

Installation

Requirements

• A PostgreSQL 13+ database
• Either:
  • A Rust toolchain with Cargo (recommended for development),
  • Node.js 18 or later with npm and
  • Open Policy Agent
• or Docker (or a compatible container runtime)

Installing from the source

1. Get the source

   git clone https://github.com/matrix-org/matrix-authentication-service.git
   cd matrix-authentication-service
   

2. Build the frontend

   cd frontend
   npm ci
   npm run build
   cd ..
   

3. Build the Open Policy Agent policies

   cd policies
   make
   cd ..
   

   OR, if you don't have opa installed and want to build through the OPA docker image

   cd policies
   make DOCKER=1
   cd ..
   

4. Compile the CLI

   cargo build --release
   

5. Grab the built binary

   cp ./target/release/mas-cli ~/.local/bin # Copy the binary somewhere in $PATH
   mas-cli --help # Should display the help message
   

Running from the Docker image

A Docker image is available here: ghcr.io/matrix-org/matrix-authentication-service:main

---

docker run --rm ghcr.io/matrix-org/matrix-authentication-service:main --help

mas-cli

USAGE:
    mas-cli [OPTIONS] [SUBCOMMAND]

FLAGS:
    -h, --help       Print help information
    -V, --version    Print version information

OPTIONS:
    -c, --config <CONFIG>...    Path to the configuration file [default: config.yaml]

SUBCOMMANDS:
    config       Configuration-related commands
    database     Manage the database
    help         Print this message or the help of the given subcommand(s)
    manage       Manage the instance
    server       Runs the web server
    templates    Templates-related commands

Note that when running in a Docker environment

---

The next step is to generate the configuration file and tweak it to reach the PostgreSQL database.

Database

You can run a PostgreSQL database locally via docker.

docker run -p 5432:5432 -e 'POSTGRES_USER=postgres' -e 'POSTGRES_PASSWORD=postgres' -e 'POSTGRES_DATABASE=postgres' postgres

Or if you uses your own shared database server you can previously create the database.

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 matrix_authentication_user

createdb --owner=matrix_authentication_user matrix_authentication