diff --git a/docs/matrix-conduit/DEPLOYMENT.md b/docs/matrix-conduit/DEPLOYMENT.md new file mode 100644 index 00000000..e92b16ab --- /dev/null +++ b/docs/matrix-conduit/DEPLOYMENT.md @@ -0,0 +1,136 @@ +# Matrix/Conduit Deployment Guide + +Executable scaffold for standing up a sovereign Matrix homeserver as the human-to-fleet command surface. + +## Architecture Summary + +``` +┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ +│ Alexander │────▶│ Nginx Proxy │────▶│ Conduit │ +│ (Element/Web) │ │ 443 / 8448 │ │ Homeserver │ +└─────────────────┘ └──────────────────┘ └─────────────────┘ + │ + ▼ + ┌─────────────────┐ + │ SQLite/Postgres│ + │ (state/media) │ + └─────────────────┘ +``` + +## Prerequisites + +| Requirement | How to Verify | Status | +|-------------|---------------|--------| +| VPS with 2GB+ RAM | `free -h` | ⬜ | +| Static IP address | `curl ifconfig.me` | ⬜ | +| Domain with A record | `dig matrix.fleet.tld` | ⬜ | +| Ports 443/8448 open | `sudo ss -tlnp | grep -E "443|8448"` | ⬜ | +| TLS certificate (Let's Encrypt) | `sudo certbot certificates` | ⬜ | +| Docker + docker-compose | `docker --version` | ⬜ | + +## Quickstart + +### 1. Host Preparation +```bash +# Ubuntu/Debian +sudo apt update && sudo apt install -y docker.io docker-compose-plugin nginx certbot + +# Open ports +sudo ufw allow 443/tcp +sudo ufw allow 8448/tcp +``` + +### 2. DNS Configuration +``` +# A record +matrix.fleet.tld. A + +# SRV for federation (optional but recommended) +_matrix._tcp.fleet.tld. SRV 10 0 8448 matrix.fleet.tld. +``` + +### 3. TLS Certificate +```bash +sudo certbot certonly --standalone -d matrix.fleet.tld +``` + +### 4. Deploy Conduit +```bash +# Edit conduit.toml: set server_name to your domain +nano conduit.toml + +# Start stack +docker compose up -d + +# Verify + docker logs -f conduit-homeserver +``` + +### 5. Nginx Configuration +```bash +sudo cp nginx-matrix.conf /etc/nginx/sites-available/matrix +sudo ln -s /etc/nginx/sites-available/matrix /etc/nginx/sites-enabled/ +sudo nginx -t && sudo systemctl reload nginx +``` + +### 6. Bootstrap Accounts +1. Open Element at `https://matrix.fleet.tld` +2. Register admin account first (while `allow_registration = true`) +3. Set admin in `conduit.toml`, restart +4. Disable registration after setup + +### 7. Fleet Rooms +```bash +# Fill ACCESS_TOKEN in bootstrap.sh +curl -X POST "https://matrix.fleet.tld/_matrix/client/r0/login" \ + -d '{"type":"m.login.password","user":"alexander","password":"YOUR_PASS"}' + +# Run bootstrap +chmod +x bootstrap.sh +./bootstrap.sh +``` + +## Federation Verification + +```bash +# Check server discovery +curl https://matrix.fleet.tld/.well-known/matrix/server +curl https://matrix.fleet.tld/.well-known/matrix/client + +# Check federation +curl https://matrix.fleet.tld:8448/_matrix/key/v2/server +``` + +## Telegram Bridge (Future) + +To bridge Telegram groups to Matrix: + +```yaml +# Add to docker-compose.yml + telegram-bridge: + image: dock.mau.dev/mautrix/telegram:latest + volumes: + - ./bridge-config.yaml:/data/config.yaml + - telegram_bridge:/data +``` + +See: https://docs.mau.fi/bridges/python/telegram/setup-docker.html + +## Security Checklist + +- [ ] Registration disabled after initial setup +- [ ] Admin list restricted +- [ ] Strong admin passwords +- [ ] Automatic security updates enabled +- [ ] Backups configured (conduit_data volume) + +## Troubleshooting + +| Issue | Cause | Fix | +|-------|-------|-----| +| Federation failures | DNS/SRV records | Verify `dig _matrix._tcp.fleet.tld SRV` | +| SSL errors | Certificate mismatches | Verify cert covers matrix.fleet.tld | +| 502 Bad Gateway | Conduit not listening | Check `docker ps`, verify port 6167 | + +--- +Generated by Ezra | Burn Mode | 2026-04-05