94c7da253e
- Adds docs/CANONICAL_INDEX_MATRIX.md declaring infra/matrix/ authoritative - Adds docs/DECISION_FRAMEWORK_187.md with Option A recommendation - Maps all legacy/duplicate paths to prevent scatter - Ezra burn mode artifact for #166 / #183 / #187 continuity
5.0 KiB
Canonical Index: Matrix/Conduit Deployment Artifacts
Issues: #166 (Execution Epic) | #183 (Scaffold — Closed) | #187 (Decision Blocker)
Created: 2026-04-05 by Ezra (burn mode)
Purpose: Single source of truth mapping every Matrix/Conduit artifact intimmy-config. Stops scatter, eliminates "which file is real?" ambiguity.
Status at a Glance
| Milestone | State | Evidence |
|---|---|---|
| Deployment scaffold | ✅ Complete | infra/matrix/ (15 files) |
| Operator runbook | ✅ Complete | docs/matrix-fleet-comms/ |
| Host readiness script | ✅ Complete | infra/matrix/host-readiness-check.sh |
| Target host selected | ⚠️ BLOCKED | Pending #187 |
| Live deployment | ⚠️ BLOCKED | Waiting on host + domain + proxy decision |
Authoritative Paths (Read/Edit These)
1. Deployment Scaffold — infra/matrix/
This is the primary executable scaffold. If you are deploying Conduit, start here and nowhere else.
| File | Purpose | Lines/Size |
|---|---|---|
README.md |
Entry point, quick-start, architecture diagram | 3,275 bytes |
prerequisites.md |
6 concrete blocking items pre-deployment | 2,690 bytes |
docker-compose.yml |
Conduit + Postgres + optional Element Web | 1,427 bytes |
conduit.toml |
Base Conduit configuration template | 1,498 bytes |
.env.example |
Environment secrets template | 1,861 bytes |
deploy-matrix.sh |
One-command deployment orchestrator | 3,388 bytes |
host-readiness-check.sh |
Pre-flight validation script | 3,321 bytes |
caddy/Caddyfile |
Reverse-proxy rules for Caddy users | 1,612 bytes |
conduit/conduit.toml |
Advanced Conduit config (federation-ready) | 2,280 bytes |
conduit/docker-compose.yml |
Extended compose with replication | 1,469 bytes |
scripts/deploy-conduit.sh |
Low-level Conduit installer | 5,488 bytes |
docs/RUNBOOK.md |
Day-2 operations (backup, upgrade, health) | 3,412 bytes |
Command for next deployer:
cd infra/matrix
./host-readiness-check.sh # 1. verify target
# Edit conduit.toml + .env
./deploy-matrix.sh # 2. deploy
2. Operator Runbook — docs/matrix-fleet-comms/
Human-facing narrative for Alexander and operators.
| File | Purpose | Size |
|---|---|---|
README.md |
Fleet communications authority map + onboarding | 7,845 bytes |
DEPLOYMENT_RUNBOOK.md |
Step-by-step operator playbook | 4,484 bytes |
Legacy / Duplicate Paths (Do Not Edit — Reference Only)
The following directories contain overlapping or superseded material. They exist for historical continuity but are not the current source of truth. If you edit these, you create divergence.
| Path | Status | Note |
|---|---|---|
deploy/matrix/ |
🔴 Superseded by infra/matrix/ |
Smaller subset; lacks host-readiness check |
deploy/conduit/ |
🔴 Superseded by infra/matrix/scripts/ |
install.sh + health.sh — good ideas ported into infra/matrix/ |
matrix/ |
🔴 Superseded by infra/matrix/ |
Early docker-compose experiment |
docs/matrix-conduit/DEPLOYMENT.md |
🔴 Superseded by docs/matrix-fleet-comms/DEPLOYMENT_RUNBOOK.md |
|
docs/matrix-deployment.md |
🔴 Superseded by infra/matrix/prerequisites.md + runbook |
|
scaffold/matrix-conduit/ |
🔴 Superseded by infra/matrix/ |
Bootstrap + nginx configs; nginx approach not chosen |
House Rule: New Matrix work must branch from
infra/matrix/ordocs/matrix-fleet-comms/. If a legacy file needs resurrection, migrate it into the authoritative tree and delete the old reference.
Decision Blocker: #187
#166 cannot proceed until #187 is resolved.
Ezra has produced a dedicated decision framework to make this a 5-minute choice rather than an architectural debate:
📄 See: docs/DECISION_FRAMEWORK_187.md
The framework recommends:
- Host: Timmy-Home bare metal (primary) or existing VPS
- Domain:
matrix.timmytime.net(or sub-domain of existing fleet domain) - Proxy: Caddy (simplest) or extend existing Traefik
- TLS: Let's Encrypt ACME HTTP-01 (port 80/443 open)
Next Agent Checklist
If you are picking up #166:
- Read
infra/matrix/README.md - Read
docs/DECISION_FRAMEWORK_187.md - Confirm resolution of #187 (host/domain/proxy chosen)
- Run
infra/matrix/host-readiness-check.shon target host - Cut a feature branch; edit
infra/matrix/conduit.tomland.env - Execute
infra/matrix/deploy-matrix.sh - Verify federation with Matrix.org test server
- Create operator room; invite Alexander
- Post SITREP on #166 with proof-of-deployment
Changelog
| Date | Change | Author |
|---|---|---|
| 2026-04-05 | Canonical index created; authoritative paths declared | Ezra |