# Synapse Homeserver Deployment Guide ## Matrix Phase 1: Deploy Synapse on Ezra VPS Part of [Epic #269: Matrix Integration — Sovereign Messaging for Timmy](https://forge.alexanderwhitestone.com/Timmy_Foundation/hermes-agent/issues/269). ## Architecture ``` ┌─────────────────────────────────────────────────┐ │ Ezra VPS (143.198.27.163) │ │ │ │ ┌──────────┐ ┌─────────────────────────┐ │ │ │ Nginx │────▶│ Synapse (Docker) │ │ │ │ :443→8008│ │ Client API: localhost:8008│ │ │ │ :8448→8448│ │ Federation: 0.0.0.0:8448│ │ │ └──────────┘ └──────────┬──────────────┘ │ │ │ │ │ ┌────────▼──────────┐ │ │ │ PostgreSQL 16 │ │ │ │ (Docker volume) │ │ │ └───────────────────┘ │ │ │ │ ┌──────────────────────────────────────────┐ │ │ │ hermes-agent (gateway) │ │ │ │ MATRIX_HOMESERVER=http://localhost:8008 │ │ │ └──────────────────────────────────────────┘ │ └─────────────────────────────────────────────────┘ ``` ## Prerequisites - Docker + Docker Compose plugin on Ezra VPS - SSH access: `ssh root@143.198.27.163` - DNS A record pointing to the VPS IP - (Recommended) Nginx + Certbot for TLS termination ## Quick Start ```bash # SSH into Ezra ssh root@143.198.27.163 # Clone hermes-agent (if not present) cd /root git clone https://forge.alexanderwhitestone.com/Timmy_Foundation/hermes-agent.git cd hermes-agent/deploy/synapse # Deploy Synapse chmod +x setup.sh ./setup.sh matrix.timmy-time.xyz # This will: # 1. Generate .env with database password # 2. Prepare homeserver.yaml # 3. Start Synapse + PostgreSQL via Docker Compose # 4. Wait for health # 5. Register admin + bot accounts # 6. Acquire bot access token # 7. Write synapse-credentials.env ``` ## Step-by-Step ### 1. DNS Configuration Point your Matrix domain to Ezra's IP: ``` Type Name Value A matrix 143.198.27.163 ``` Federation uses SRV records for port discovery, but direct `:8448` works without them. ### 2. Deploy Synapse ```bash cd /root/hermes-agent/deploy/synapse ./setup.sh matrix.timmy-time.xyz hermes-bot 'your-secure-password' ``` Arguments: | Arg | Default | Description | |-----|---------|-------------| | `server_name` | (required) | Matrix domain (e.g., `matrix.timmy-time.xyz`) | | `admin_user` | `timmy-admin` | Admin account username | | `admin_password` | (random) | Admin account password | | `bot_user` | `hermes-bot` | Bot account username | | `bot_password` | (random) | Bot account password | ### 3. TLS Termination (Nginx) Install Nginx + Certbot: ```bash apt install -y nginx certbot python3-certbot-nginx # Client-server API cat > /etc/nginx/sites-available/matrix <<'EOF' server { listen 443 ssl http2; server_name matrix.timmy-time.xyz; ssl_certificate /etc/letsencrypt/live/matrix.timmy-time.xyz/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/matrix.timmy-time.xyz/privkey.pem; location / { proxy_pass http://127.0.0.1:8008; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; client_max_body_size 50M; } } server { listen 8448 ssl http2; server_name matrix.timmy-time.xyz; ssl_certificate /etc/letsencrypt/live/matrix.timmy-time.xyz/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/matrix.timmy-time.xyz/privkey.pem; location / { proxy_pass http://127.0.0.1:8008; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } } EOF ln -sf /etc/nginx/sites-available/matrix /etc/nginx/sites-enabled/ nginx -t && systemctl reload nginx # Get cert certbot --nginx -d matrix.timmy-time.xyz ``` ### 4. Wire Hermes Agent Copy the generated credentials to hermes-agent's environment: ```bash # From synapse-credentials.env, add to ~/.hermes/.env: MATRIX_HOMESERVER=https://matrix.timmy-time.xyz MATRIX_ACCESS_TOKEN= MATRIX_USER_ID=@hermes-bot:matrix.timmy-time.xyz MATRIX_DEVICE_ID= MATRIX_ENCRYPTION=true ``` Then start the gateway: ```bash hermes gateway --platform matrix ``` ### 5. Verify ```bash # Check Synapse health curl -s https://matrix.timmy-time.xyz/_matrix/client/versions # Check federation curl -s https://matrix.timmy-time.xyz:8448/_matrix/federation/v1/version # Check bot is connected # (should appear online in Element or any Matrix client) ``` ## Management Use the management script for day-to-day operations: ```bash cd /root/hermes-agent/deploy/synapse ./manage.sh status # container health ./manage.sh logs # tail logs ./manage.sh restart # restart Synapse ./manage.sh backup # backup DB + data ./manage.sh update # pull latest image ./manage.sh create-user alice 'password123' ./manage.sh create-user admin 'secret' admin ``` ## Backups ```bash ./manage.sh backup # Creates: backups/YYYYMMDD_HHMMSS/ # ├── synapse_db.sql (PostgreSQL dump) # └── synapse_data.tar.gz (media store + keys) ``` Automate with cron: ```bash # Daily backup at 3 AM 0 3 * * * cd /root/hermes-agent/deploy/synapse && ./manage.sh backup >> /var/log/synapse-backup.log 2>&1 ``` ## Troubleshooting ### Synapse won't start ```bash docker compose logs synapse # Common: PostgreSQL not ready. Wait for healthcheck. ``` ### Bot can't connect ```bash # Verify token is valid curl -H "Authorization: Bearer $MATRIX_ACCESS_TOKEN" \ https://matrix.timmy-time.xyz/_matrix/client/v3/account/whoami ``` ### Federation not working ```bash # Check port 8448 is open ss -tlnp | grep 8448 # Check firewall ufw status ``` ### High memory usage ```bash # Check resource limits in docker-compose.yml docker stats synapse # Tune in homeserver.yaml: event_cache_size, caches ``` ## Security Notes - Registration is disabled by default (`enable_registration: false`) - Rate limiting is enforced on login, registration, and messages - Federation certificate verification is enabled - `.env` and `synapse-credentials.env` are `chmod 600` - Client API binds to `127.0.0.1` only (use Nginx for public access) - Consider: firewall rules, fail2ban, regular backups ## References - [Synapse Documentation](https://matrix-org.github.io/synapse/latest/) - [Matrix Spec](https://spec.matrix.org/) - [Epic #269: Matrix Integration](https://forge.alexanderwhitestone.com/Timmy_Foundation/hermes-agent/issues/269) - [Issue #272: Deploy Synapse on Ezra](https://forge.alexanderwhitestone.com/Timmy_Foundation/hermes-agent/issues/272) - [Hermes Matrix Setup Guide](docs/matrix-setup.md)