timmy-config/docs/matrix-deployment.md

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:

# 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    <timmy-home-ip>

# 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.