Docs: include syn2mas docker option

[matrixbot]

This issue was originally created by @joepitt91 at matrix-org/matrix-authentication-service#2912.

After a bit of trail and error I've successfully migrated my synapse server that was using oidc_providers: to use experimental_features: msc3861:.

The only real feedback I've got on the process is that it would be good if the docs pointed to the docker container for syn2mas and how to use it as I didn't find this bit clear, especially how to map old OIDC realm to new MAS realm.

Suggested commands for docs:

# Alias syn2mas for readability and ease of typing
alias syn2mas='docker run --rm -v /srv/docker/matrix/mas-config.yaml:/mas.yml -v /srv/docker/matrix/server/homeserver.yaml:/homeserver.yaml ghcr.io/matrix-org/matrix-authentication-service/syn2mas'

# Run the advisor
syn2mas --command advisor --synapseConfigFile /homeserver.yaml

# Do a dry run and check output
syn2mas --command migrate --synapseConfigFile /homeserver.yaml --masConfigFile /mas.yaml --upstreamProviderMapping oidc-keycloak:00000000000000000000000000 --dryRun

# Stop the server
docker compose down

# Do the migration
syn2mas --command migrate --synapseConfigFile /homeserver.yaml --masConfigFile /mas.yaml --upstreamProviderMapping oidc-keycloak:00000000000000000000000000 --dryRun false

# Remove the alias as it is no longer needed
unalias syn2mas

# Bring the server back up
docker compose up -d

In case it is useful for the docs too, this is my current docker-compose.yml which seems to work well - upstream HTTPS reverse proxy then proxies to 10.0.0.1:80 and 10.0.0.1:8080 for matrix.domain.tld and mas.domain.tld respectively.

---
services:
  client:
    container_name: matrix-element
    depends_on:
      server:
        condition: service_healthy
    healthcheck:
      test: wget --no-verbose --tries=1 --spider http://127.0.0.1/#/welcome || exit 1
    image: vectorim/element-web:latest
    restart: unless-stopped
    volumes:
      - ./client.json:/app/config.json
  proxy:
    container_name: matrix-reverse-proxy
    depends_on:
      client:
        condition: service_healthy
      mas:
        condition: service_healthy
      server:
        condition: service_healthy
      sliding-sync:
        condition: service_healthy
    healthcheck:
      test: curl --fail http://127.0.0.1/_matrix/client/versions || exit 1
    image: nginx:1.25
    ports:
      - 10.0.0.1:80:80/tcp
    restart: unless-stopped
    volumes:
      - ./proxy.conf:/etc/nginx/conf.d/default.conf:ro
  server:
    container_name: matrix-server
    environment:
      - SYNAPSE_CONFIG_PATH=/data/homeserver.yaml
    image: ghcr.io/element-hq/synapse:latest
    restart: unless-stopped
    volumes:
      - ./server:/data
  sliding-sync:
    container_name: matrix-sync-server
    depends_on:
      server:
        condition: service_healthy
    healthcheck:
      # best option found so far
      test: if [ "$(curl --write-out '%{http_code}' --silent --output /dev/null http://127.0.0.1:8008/_matrix/client/unstable/org.matrix.msc3575/sync)" = "405" ]; then exit 0; else exit 1; fi
    environment:
      - SYNCV3_SERVER=http://server:8008
      - SYNCV3_SECRET=[redcated]
      - SYNCV3_BINDADDR=:8008
      - SYNCV3_DB=user=synapse dbname=slidingsync sslmode=require host=[redacted] password='[redacted]'
    image: ghcr.io/matrix-org/sliding-sync:latest
    restart: unless-stopped
  mas:
    container_name: matrix_mas
    healthcheck:
      test: ["CMD", "mas-cli", "config", "check"]
    image: ghcr.io/matrix-org/matrix-authentication-service:main
    ports:
      - 10.0.0.1:8080:8080
    restart: unless-stopped
    volumes:
      - ./mas-config.yaml:/config.yaml

Hopefully this is useful feedback 🤞