timmy-config/infra/matrix/README.md

Matrix/Conduit Deployment Scaffold

Parent: #166 | Scaffold task: #183

This directory contains an executable deployment path for standing up a Matrix homeserver (Conduit) for sovereign human-to-fleet encrypted communication.

Status

Component	State
Deployment scaffold	✅ Present
Target host	⚠️ Requires selection
Reverse proxy (Caddy/Nginx)	⚠️ Pending host provisioning
TLS certificates	⚠️ Pending DNS + proxy setup
Federation	⚠️ Pending DNS SRV records
Fleet bot integration	⚠️ Post-deployment

Quick Start

cd /path/to/timmy-config/infra/matrix
# 1. Read prerequisites.md — ensure host is ready
# 2. Edit conduit.toml with your domain
# 3. Copy .env.example → .env and fill secrets
# 4. Run: ./deploy-matrix.sh

Architecture

┌─────────────────────────────────────────────────────────────┐
│                        Host (VPS)                           │
│  ┌─────────────────┐      ┌──────────────────────────────┐  │
│  │  Caddy/Nginx    │─────▶│  Conduit (Matrix homeserver) │  │
│  │  :443/:8448     │      │  :6167 (internal)            │  │
│  └─────────────────┘      └──────────────────────────────┘  │
│           │                            │                    │
│           ▼                            ▼                    │
│     TLS termination          SQLite/RocksDB storage         │
│     Let's Encrypt            Config: conduit.toml           │
└─────────────────────────────────────────────────────────────┘

Files

File	Purpose
prerequisites.md	Host requirements, ports, DNS, decisions
docker-compose.yml	Conduit + optionally Element-Web
conduit.toml	Homeserver configuration scaffold
deploy-matrix.sh	One-command deployment script
.env.example	Environment variable template
caddy/Caddyfile	Reverse proxy configuration

Post-Deployment

1. Create admin account via registration or CLI
2. Create fleet rooms (encrypted by default)
3. Onboard Alexander as operator
4. Deploy fleet bots (Hermes gateway with Matrix platform adapter)
5. Evaluate Telegram-to-Matrix bridge (mautrix-telegram)

Decisions Log

• Homeserver: Conduit (lightweight, Rust, single binary, SQLite default)
• Database: SQLite for single-host; migrate to PostgreSQL if scale demands
• Reverse proxy: Caddy (automatic HTTPS) or Nginx (existing familiarity)
• Client: Element Web (optional, self-hosted) + native apps
• Federation: Enabled (required for multi-homeserver fleet topology)