Host Matrix (Synapse) on an Offshore VPS

# ── One-time setup, run in order on Ubuntu 24.04 (Docker + compose-plugin installed) ──
#
# 1. Generate Synapse's config (replace matrix.example.com with your real domain):
#    mkdir -p synapse-data pgdata
#    docker run --rm -v "$(pwd)/synapse-data:/data" \
#      -e SYNAPSE_SERVER_NAME=matrix.example.com \
#      -e SYNAPSE_REPORT_STATS=no \
#      ghcr.io/element-hq/synapse:latest generate
#
# 2. In synapse-data/homeserver.yaml, REPLACE the generated sqlite `database:`
#    block with the postgres block shown at the bottom of this file, and add
#    `x_forwarded: true` under the port-8008 listener (you are behind a proxy).
#
# 3. Bring the stack up:  docker compose up -d
#
# 4. Create your admin user:
#    docker compose exec synapse register_new_matrix_user \
#      -u admin -a -c /data/homeserver.yaml http://localhost:8008
#
# 5. Put a TLS reverse proxy (Caddy/nginx) on 443 -> 127.0.0.1:8008 and serve
#    /.well-known/matrix/server + /.well-known/matrix/client for federation.

services:
  db:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: synapse
      POSTGRES_PASSWORD: CHANGE_ME_STRONG_DB_PASSWORD
      POSTGRES_DB: synapse
      # Synapse REQUIRES the DB to use C locale — this is a hard requirement:
      POSTGRES_INITDB_ARGS: "--encoding=UTF8 --locale=C"
    volumes:
      - ./pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U synapse"]
      interval: 10s
      timeout: 5s
      retries: 5

  synapse:
    image: ghcr.io/element-hq/synapse:latest
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    environment:
      SYNAPSE_SERVER_NAME: matrix.example.com
      SYNAPSE_REPORT_STATS: "no"
    volumes:
      - ./synapse-data:/data
    ports:
      # Client + federation HTTP. Bound to localhost — TLS is terminated by
      # your reverse proxy. Never expose 8008 to the internet in the clear.
      - "127.0.0.1:8008:8008"

# ── Paste this into synapse-data/homeserver.yaml, replacing the sqlite block ──
# database:
#   name: psycopg2
#   args:
#     user: synapse
#     password: CHANGE_ME_STRONG_DB_PASSWORD
#     dbname: synapse
#     host: db
#     port: 5432
#     cp_min: 5
#     cp_max: 10