5.9 KiB
Decision Framework: Matrix Host, Domain, and Proxy (#187)
Parent: #166 — Stand up Matrix/Conduit for human-to-fleet encrypted communication
Blocker: #187 — Decide Matrix host, domain, and proxy prerequisites
Author: Ezra
Date: 2026-04-05
Executive Summary
#166 is execution-ready. The only remaining gate is three decisions:
- Host — which machine runs Conduit?
- Domain — what FQDN serves the homeserver?
- Proxy/TLS — how do HTTPS and federation terminate?
This document provides recommended decisions with full trade-off analysis. If Alexander accepts the recommendations, #187 can close immediately and deployment can begin within the hour.
Decision 1: Host
Recommended Choice
Hermes VPS (current host of Ezra, Bezalel, and Allegro-Primus gateway).
Alternative Considered
TestBed VPS (67.205.155.108) — currently hosts Bezalel (stale) and other experimental workloads.
Comparison
| Factor | Hermes VPS | TestBed VPS |
|---|---|---|
| Disk | ✅ 55 GB free | Unknown / smaller |
| RAM | ✅ 7 GB | 4 GB (reported) |
| Docker | ✅ Installed | Unknown |
| Docker Compose | ❌ Not installed (15-min fix) | Unknown |
| Nginx on 80/443 | ✅ Already running | Unknown |
| Tailscale | ✅ Active | Unknown |
| Existing wizard presence | ✅ Ezra, Bezalel, Allegro-Primus | ❌ None primary |
| Latency to Alexander | Low (US East) | Low (US East) |
Ezra Recommendation
Hermes VPS. It has the resources, the existing fleet footprint, and the lowest operational surprise. The only missing package is Docker Compose, which is a one-line install (apt install docker-compose-plugin or pip install docker-compose).
Decision 2: Domain / Subdomain
Recommended Choice
matrix.alexanderwhitestone.com
Alternatives Considered
fleet.alexanderwhitestone.comchat.alexanderwhitestone.comconduit.alexanderwhitestone.com
Analysis
| Subdomain | Clarity | Federation Friendly | Notes |
|---|---|---|---|
matrix.* |
✅ Industry standard | ✅ Easy to remember | Best for .well-known/matrix/server delegation |
fleet.* |
⚠️ Ambiguous (could be any fleet service) | ⚠️ Fine, but less obvious | Good branding, worse discoverability |
chat.* |
✅ User friendly | ⚠️ Suggests a web app, not a homeserver | Fine for Element Web, less precise for federation |
conduit.* |
⚠️ Ties us to one implementation | ✅ Fine | If we ever switch to Synapse, this ages poorly |
Ezra Recommendation
matrix.alexanderwhitestone.com because it is unambiguous, implementation-agnostic, and follows Matrix community convention. The server name can still be alexanderwhitestone.com (for short Matrix IDs like @ezra:alexanderwhitestone.com) while the actual homeserver listens on matrix.alexanderwhitestone.com:8448 or is delegated via .well-known.
Decision 3: Reverse Proxy / TLS
Recommended Choice
Nginx (already on 80/443) reverse-proxies to Conduit; Let’s Encrypt for TLS.
Two Viable Patterns
Pattern A: Nginx → Conduit directly (Recommended)
Internet → Nginx (443) → Conduit (6167 internal)
Internet → Nginx (8448) → Conduit (8448 internal)
- Nginx handles TLS termination.
- Conduit runs plain HTTP on an internal port.
- Federation port 8448 is exposed through Nginx stream or server block.
Pattern B: Nginx → Caddy → Conduit
Internet → Nginx (443) → Caddy (4443) → Conduit (6167)
- Caddy automates Let’s Encrypt inside the Compose network.
- Nginx remains the edge listener.
- More moving parts, but Caddy’s on-demand TLS is convenient.
Comparison
| Concern | Pattern A (Nginx direct) | Pattern B (Nginx → Caddy) |
|---|---|---|
| Moving parts | Fewer | More |
| TLS automation | Manual certbot or certbot-nginx | Caddy handles it |
| Config complexity | Medium | Medium-High |
| Debuggability | Easier (one proxy hop) | Harder (two hops) |
| Aligns with existing Nginx | ✅ Yes | ⚠️ Needs extra upstream |
Ezra Recommendation
Pattern A for initial deployment. Nginx is already the edge proxy on Hermes VPS. Adding one server {} block and one location /_matrix/ block is the shortest path to a working homeserver. If TLS automation becomes a burden, we can migrate to Caddy later without changing Conduit’s configuration.
Pre-Deployment Checklist (Post-#187)
Once the decisions above are ratified, the exact execution sequence is:
- Install Docker Compose on Hermes VPS (if not already present).
- Create DNS A record for
matrix.alexanderwhitestone.com→ Hermes VPS public IP. - Obtain TLS certificate for
matrix.alexanderwhitestone.com(certbot or manual). - Copy Nginx server block from
infra/matrix/caddy/or write a minimal reverse-proxy config. - Run
./host-readiness-check.shand confirm all checks pass. - Run
./deploy-matrix.shand wait for Conduit to come online. - Run
python3 scripts/bootstrap-fleet-rooms.py --create-allto initialize rooms. - Run
./scripts/verify-hermes-integration.shto prove E2EE messaging works. - Follow
docs/matrix-fleet-comms/CUTOVER_PLAN.mdfor the Telegram → Matrix transition.
Accountability Matrix
| Decision | Recommended Option | Decision Owner | Execution Owner |
|---|---|---|---|
| Host | Hermes VPS | @allegro / @timmy | @ezra |
| Domain | matrix.alexanderwhitestone.com |
@rockachopa | @ezra |
| Proxy/TLS | Nginx direct (Pattern A) | @ezra / @allegro | @ezra |
Ezra Stance
#166 has been reduced from a fuzzy epic to a three-decision, ten-step execution. All architecture, verification scripts, and contingency plans are in repo truth. The only missing ingredient is a yes/no on the three decisions above.
— Ezra, Archivist