VuongKB/infrastructure/vm-102-matrix-synapse.md

created, id, keywords, links, modified, summary, tags, title

created	id	keywords	links	modified	summary	tags	title
2026-04-11T16:32:16+00:00	96c4de5f-0dd1-4cdb-a13d-dca95cf3ebcb	matrix.pfi.local synapse element-web 10.250.50.70 VM-102 PFI-ANA-Docker postgres:16 appservice AIPA		2026-04-11T16:32:16+00:00	Docker deployment of Synapse homeserver with PostgreSQL and Element Web on VM 102 (PFI-ANA-Docker). Covers compose file, configuration, storage paths, and admin setup.	infrastructure pfi pfi-ana matrix docker vm-102 synapse self-hosted deployment	VM 102 — Matrix Synapse Deployment

VM 102 (PFI-ANA-Docker, 10.250.50.70) hosts the Matrix stack as the primary human-to-agent communication channel for AIPA.

Components

Component	Image	Port	Purpose
synapse	matrixdotorg/synapse:latest	8008	Matrix homeserver (Client-Server API)
synapse-db	postgres:16	—	Synapse database
element-web	vectorim/element-web:latest	8080	Web client for users

Storage Paths

Host Path	Purpose
/opt/docker/compose/synapse/	Compose file (managed by Dockge)
/opt/docker/conf/synapse/	Configuration files
/opt/docker/data/synapse/	Synapse data (homeserver.yaml, signing keys, appservice reg)

Volumes

Volume / Path	Container Path	Purpose
/opt/docker/data/synapse	/data	Synapse config, signing keys, media store
synapse-db-data (named vol)	/var/lib/postgresql/data	PostgreSQL persistent data

Deployment Steps

1. Create directories

mkdir -p /opt/docker/data/synapse
mkdir -p /opt/docker/conf/synapse
mkdir -p /opt/docker/compose/synapse

2. Generate Synapse config

docker run --rm \
  -v /opt/docker/data/synapse:/data \
  -e SYNAPSE_SERVER_NAME=matrix.pfi.local \
  -e SYNAPSE_REPORT_STATS=no \
  matrixdotorg/synapse:latest generate

Do not modify server_name after generation — it is permanent.

3. Edit homeserver.yaml

database:
  name: psycopg2
  args:
    user: synapse
    password: synapse_db_password
    database: synapse
    host: synapse-db
    cp_min: 5
    cp_max: 10

enable_registration: false
federation_domain_whitelist: []

app_service_config_files:
  - /data/aipa_appservice.yaml

4. Docker Compose

File: /opt/docker/compose/synapse/docker-compose.yml

---
services:
  synapse-db:
    image: postgres:16
    container_name: synapse-db
    restart: unless-stopped
    environment:
      POSTGRES_USER: synapse
      POSTGRES_PASSWORD: synapse_db_password
      POSTGRES_DB: synapse
      POSTGRES_INITDB_ARGS: "--encoding=UTF-8 --lc-collate=C --lc-ctype=C"
    volumes:
      - synapse-db-data:/var/lib/postgresql/data
    networks:
      - synapse-net
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U synapse"]
      interval: 10s
      timeout: 5s
      retries: 5

  synapse:
    image: matrixdotorg/synapse:latest
    container_name: synapse
    restart: unless-stopped
    depends_on:
      synapse-db:
        condition: service_healthy
    ports:
      - "8008:8008"
    volumes:
      - /opt/docker/data/synapse:/data
    networks:
      - synapse-net
    deploy:
      resources:
        limits:
          memory: 1G
          cpus: "2.0"
        reservations:
          memory: 256M
    healthcheck:
      test: ["CMD-SHELL", "curl -fsS http://localhost:8008/health || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 30s

  element-web:
    image: vectorim/element-web:latest
    container_name: element-web
    restart: unless-stopped
    volumes:
      - /opt/docker/conf/synapse/element-config.json:/app/config.json:ro
    ports:
      - "8080:80"
    networks:
      - synapse-net

volumes:
  synapse-db-data:

networks:
  synapse-net:
    name: synapse-net

Start: cd /opt/docker/compose/synapse && docker compose up -d Verify: curl http://localhost:8008/health

5. Element Web config

File: /opt/docker/conf/synapse/element-config.json

{
    "default_server_config": {
        "m.homeserver": {
            "base_url": "http://10.250.50.70:8008",
            "server_name": "matrix.pfi.local"
        }
    },
    "brand": "AIPA",
    "default_theme": "dark",
    "disable_guests": true,
    "disable_login_language_selector": true
}

6. Create admin user

docker exec -it synapse register_new_matrix_user -u admin -p 'yourpassword' -a http://localhost:8008

Agent users (@atlas, @linus, @hermione) are virtual — managed by the appservice. Do not register them as real accounts.

Network

Uses dedicated synapse-net (not traefik-net) because Synapse is accessed directly by IP. If TLS/reverse proxy is needed later, join traefik-net and add Traefik labels.

Port Allocation

Port	Service	Protocol
8008	Synapse	HTTP
8080	Element Web	HTTP
8009	AIPA Bridge	HTTP

Security Notes

• Registration disabled (enable_registration: false)
• Federation disabled (federation_domain_whitelist: [])
• as_token and hs_token are admin-equivalent secrets — store in env.sh, never commit
• For external access, put behind TLS-terminating reverse proxy