update installation documentation

README.md

@@ -7,31 +7,14 @@ See the [Documentation](https://matrix-org.github.io/matrix-authentication-servi
 
 ## Running
 
-- [Install Rust and Cargo](https://www.rust-lang.org/learn/get-started)
-- [Install Node.js and npm](https://nodejs.org/)
-- [Install Open Policy Agent](https://www.openpolicyagent.org/docs/latest/#1-download-opa)
-- Clone this repository
-- Build the frontend
-  ```sh
-  cd frontend
-  npm ci
-  npm run build
-  cd ..
-  ```
-- Build the Open Policy Agent policies
-  ```sh
-  cd policies
-  make
-  # OR, if you don't have `opa` installed and want to build through the OPA docker image
-  make DOCKER=1
-  cd ..
-  ```
-- Generate the sample config via `cargo run -- config generate > config.yaml`
-- Run a PostgreSQL database locally
-  ```sh
-  docker run -p 5432:5432 -e 'POSTGRES_USER=postgres' -e 'POSTGRES_PASSWORD=postgres' -e 'POSTGRES_DATABASE=postgres' postgres
-  ```
-- Update the database URI in `config.yaml` to `postgresql://postgres:postgres@localhost/postgres`
-- Run the database migrations via `cargo run -- database migrate`
-- Run the server via `cargo run -- server -c config.yaml`
+- [Observe and install requirements](https://matrix-org.github.io/matrix-authentication-service/usage/installation.html#requirements)
+- [Install Matrix Authentication Service](https://matrix-org.github.io/matrix-authentication-service/usage/installation.html#installing-from-the-source)
+- [Generate the sample config](https://matrix-org.github.io/matrix-authentication-service/usage/configuration.html)
+- [Provide the database](https://matrix-org.github.io/matrix-authentication-service/usage/installation.html#database)
+- [Customize your minimal configuration](https://matrix-org.github.io/matrix-authentication-service/usage/configuration.html#minimal-configuration)
+  - `database.uri`
+- [Run the database migrations](https://matrix-org.github.io/matrix-authentication-service/usage/usage.html#running)
+- [Run the server](https://matrix-org.github.io/matrix-authentication-service/usage/usage.html#running)
 - Go to <http://localhost:8080/>
+
+- Or use the [docker image](https://matrix-org.github.io/matrix-authentication-service/usage/installation.html#running-from-the-docker-image) alternatively.

docs/usage/configuration.md

@@ -32,6 +32,11 @@ docker run --rm -v `pwd`/config.yaml:/config.yaml \
 
 Note that with Docker, the config file must be mounted inside the container with `-v/--volume`.
 
+Update the database URI in `config.yaml` to your database,
+e.g. `postgresql://postgres:postgres@localhost/postgres`
+
+See also the next paragraph for a [minimum configuration ](#minimal-configuration)
+
 ## Minimal configuration
 
 Here is a minimal configuration needed to have the server running.
@@ -97,14 +102,32 @@ Controls the web server.
 
 ```yaml
 http:
-  # On what address and port the server should listen to
-  address: 0.0.0.0:8080
-
-  # Path from which to serve static files
-  web_root: /var/www/static
-
+  listeners:
+  - name: web
+    resources:
+    - name: discovery
+    - name: human
+    - name: oauth
+    - name: compat
+    - name: graphql
+      playground: true
+    - name: assets
+      # Path from which to serve static files
+      path: ./frontend/dist/
+    binds:
+    # On what address and port the server should listen to
+    - address: '[::]:8080'
+    proxy_protocol: false
+  - name: internal
+    resources:
+    - name: health
+    binds:
+    - host: localhost
+      port: 8081
+    proxy_protocol: false
   # Public URL base used when building absolute public URLs
-  public_base: http://localhost:8080
+  public_base: http://[::]:8080/
+  issuer: http://[::]:8080/
 ```
 
 ### `database`

docs/usage/installation.md

@@ -4,8 +4,10 @@
 
  - A PostgreSQL database
  - Either:
-   - A [Rust toolchain](https://www.rust-lang.org/learn/get-started) (recommended for development)
-   - or [Docker](https://www.docker.com/get-started) (or a compatible container runtime)
+   - A [Rust and Cargo toolchain](https://www.rust-lang.org/learn/get-started) (recommended for development),
+   - [Node.js and npm](https://nodejs.org/) and
+   - [Open Policy Agent](https://www.openpolicyagent.org/docs/latest/#1-download-opa)
+ - **or** [Docker](https://www.docker.com/get-started) (or a compatible container runtime)
 
 ## Installing from the source
 
@@ -14,12 +16,31 @@
    git clone https://github.com/matrix-org/matrix-authentication-service.git
    cd matrix-authentication-service
    ```
-2. Compile the CLI
+1. Build the frontend
+   ```sh
+   cd frontend
+   npm ci
+   npm run build
+   cd ..
    ```
+1. Build the Open Policy Agent policies
+   ```sh
+   cd policies
+   make
+   cd ..
+   ```
+   OR, if you don't have `opa` installed and want to build through the OPA docker image
+   ```sh
+   cd policies
+   make DOCKER=1
+   cd ..
+   ```
+1. Compile the CLI
+   ```sh
    cargo build --release
    ```
-3. Grab the built binary
-   ```
+1. Grab the built binary
+   ```sh
    cp ./target/release/mas-cli ~/.local/bin # Copy the binary somewhere in $PATH
    mas-cli --help # Should display the help message
    ```
@@ -60,3 +81,28 @@ 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.
+```sh
+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:
+
+```sh
+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
+```