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