feat(synapse): Matrix Phase 1 — Synapse homeserver deployment stack
Some checks failed
Forge CI / smoke-and-build (pull_request) Failing after 1m1s
Some checks failed
Forge CI / smoke-and-build (pull_request) Failing after 1m1s
Deploy Synapse on Ezra VPS with PostgreSQL backend, bot registration, and management tooling. Closes #272 Components: - docker-compose.yml: Synapse + PostgreSQL 16 stack - homeserver.yaml: Production config (registration disabled, rate limits, retention) - setup.sh: One-shot deploy (generates secrets, starts stack, registers accounts, gets bot token) - manage.sh: Day-to-day ops (status, restart, logs, backup, update, create-user, teardown) - docs/synapse-deployment.md: Full deployment guide with Nginx TLS, DNS, troubleshooting Security: - Registration disabled by default - Rate limiting on login/registration/messages - Client API bound to localhost (Nginx proxy for public access) - Secrets chmod 600, .gitignore'd - Federation certificate verification enabled Bot account auto-registered and access token acquired — credentials written to synapse-credentials.env for hermes-agent integration.
This commit is contained in:
Alexander Whitestone
251
docs/synapse-deployment.md
Normal file
251
docs/synapse-deployment.md
Normal file
@@ -0,0 +1,251 @@
|
||||
# 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=<from synapse-credentials.env>
|
||||
MATRIX_USER_ID=@hermes-bot:matrix.timmy-time.xyz
|
||||
MATRIX_DEVICE_ID=<from synapse-credentials.env>
|
||||
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)
|
||||
Reference in New Issue
Block a user