Create: infrastructure/vm-102-matrix-synapse.md

2026-04-11 09:32:16 -07:00
parent 18265d33ec
commit 9a1c624d08
1 changed files with 214 additions and 0 deletions
@@ -0,0 +1,214 @@
+---
+created: '2026-04-11T16:32:16+00:00'
+id: 96c4de5f-0dd1-4cdb-a13d-dca95cf3ebcb
+keywords:
+- matrix.pfi.local
+- synapse
+- element-web
+- 10.250.50.70
+- VM-102
+- PFI-ANA-Docker
+- postgres:16
+- appservice
+- AIPA
+links: []
+modified: '2026-04-11T16:32:16+00:00'
+summary: 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.
+tags:
+- infrastructure
+- pfi
+- pfi-ana
+- matrix
+- docker
+- vm-102
+- synapse
+- self-hosted
+- deployment
+title: 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
+```bash
+mkdir -p /opt/docker/data/synapse
+mkdir -p /opt/docker/conf/synapse
+mkdir -p /opt/docker/compose/synapse
+```
+
+### 2. Generate Synapse config
+```bash
+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
+
+```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
+
+```yaml
+---
+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
+
+```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
+```bash
+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