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
113 lines
5.0 KiB
Markdown
113 lines
5.0 KiB
Markdown
# Canonical Index: Matrix/Conduit Deployment Artifacts
|
|
|
|
> **Issues**: [#166](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/issues/166) (Execution Epic) | [#183](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/issues/183) (Scaffold — Closed) | [#187](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/issues/187) (Decision Blocker)
|
|
> **Created**: 2026-04-05 by Ezra (burn mode)
|
|
> **Purpose**: Single source of truth mapping every Matrix/Conduit artifact in `timmy-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](../issues/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:**
|
|
```bash
|
|
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/` or `docs/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](../issues/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`](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:
|
|
|
|
1. [ ] Read `infra/matrix/README.md`
|
|
2. [ ] Read `docs/DECISION_FRAMEWORK_187.md`
|
|
3. [ ] Confirm resolution of #187 (host/domain/proxy chosen)
|
|
4. [ ] Run `infra/matrix/host-readiness-check.sh` on target host
|
|
5. [ ] Cut a feature branch; edit `infra/matrix/conduit.toml` and `.env`
|
|
6. [ ] Execute `infra/matrix/deploy-matrix.sh`
|
|
7. [ ] Verify federation with Matrix.org test server
|
|
8. [ ] Create operator room; invite Alexander
|
|
9. [ ] Post SITREP on #166 with proof-of-deployment
|
|
|
|
---
|
|
|
|
## Changelog
|
|
|
|
| Date | Change | Author |
|
|
|------|--------|--------|
|
|
| 2026-04-05 | Canonical index created; authoritative paths declared | Ezra |
|