diff --git a/docs/matrix-deployment.md b/docs/matrix-deployment.md new file mode 100644 index 00000000..a5ec209f --- /dev/null +++ b/docs/matrix-deployment.md @@ -0,0 +1,86 @@ +# Matrix/Conduit Deployment Guide + +> **Parent**: timmy-config#166 +> **Child**: timmy-config#183 +> **Created**: 2026-04-05 by Ezra burn-mode triage + +## Deployment Prerequisites + +### 1. Host Selection Matrix + +| Option | Pros | Cons | Recommendation | +|--------|------|------|----------------| +| Timmy-Home bare metal | Full sovereignty, existing Traefik | Single point of failure, home IP | **PRIMARY** | +| DigitalOcean VPS | Static IP, offsite | Monthly cost, external dependency | BACKUP | +| RunPod GPU instance | Already in fleet | Ephemeral, not for persistence | NOT SUITABLE | + +### 2. Port Requirements + +| Port | Purpose | Inbound Required | +|------|---------|------------------| +| 8448 | Federation (server-to-server) | Yes | +| 443 | Client HTTPS | Yes (via Traefik) | +| 80 | ACME HTTP-01 challenge | Yes (redirects to 443) | +| 6167 | Conduit replication (optional) | Internal only | + +### 3. Reverse Proxy Assumptions (Traefik) + +Existing `timmy-home` Traefik instance can route Matrix traffic: + +```yaml +# docker-compose.yml labels for Conduit +labels: + - "traefik.enable=true" + - "traefik.http.routers.matrix.rule=Host(`matrix.tactical.local`)" + - "traefik.http.routers.matrix.tls.certresolver=letsencrypt" + - "traefik.http.services.matrix.loadbalancer.server.port=6167" + # Federation SRV delegation + - "traefik.tcp.routers.matrix-federation.rule=HostSNI(`*`)" + - "traefik.tcp.routers.matrix-federation.entrypoints=federation" +``` + +### 4. DNS Requirements + +``` +# A records +matrix.tactical.local A + +# SRV records for federation +_matrix._tcp.tactical.local SRV 10 0 8448 matrix.tactical.local +``` + +### 5. Database Choice + +| Option | When to Use | +|--------|-------------| +| SQLite (default) | < 100 users, < 10 rooms, single-node | +| PostgreSQL | Scale, backups, multi-node potential | + +**Recommendation**: Start with SQLite. Migrate to PostgreSQL only if federation grows. + +### 6. Storage Requirements + +- Conduit binary: ~50MB +- Database (SQLite): ~100MB initial, grows with media +- Media repo: Plan for 10GB (images, avatars, room assets) + +## Blocking Prerequisites Checklist + +- [ ] **Host**: Confirm Timmy-Home static IP or dynamic DNS +- [ ] **Ports**: Verify 8448, 443, 80 not blocked by ISP +- [ ] **Traefik**: Confirm federation TCP entrypoint configured +- [ ] **DNS**: SRV records creatable at domain registrar +- [ ] **SSL**: Let's Encrypt ACME configured in Traefik +- [ ] **Backup**: Volume mount strategy for SQLite persistence + +## Next Steps + +1. Complete prerequisites checklist above +2. Generate `conduit-config.toml` (see `matrix/conduit-config.toml`) +3. Create `docker-compose.yml` with Traefik labels +4. Deploy test room with @ezra + Alexander +5. Verify client connectivity (Element web/iOS) +6. Document Telegram→Matrix migration plan + +--- +*This document lowers #166 from fuzzy epic to executable deployment steps.*