timmy-config/infra/matrix/docs/RUNBOOK.md

Matrix/Conduit Operational Runbook

This document contains operational procedures for the Timmy Foundation Matrix infrastructure.

Quick Reference

Task	Command
Start server	cd infra/matrix/conduit && docker compose up -d
View logs	cd infra/matrix/conduit && docker compose logs -f
Create admin account	./scripts/deploy-conduit.sh admin
Backup data	./scripts/deploy-conduit.sh backup
Check status	./scripts/deploy-conduit.sh status

Initial Setup Checklist

• DNS A record pointing to host IP (matrix.yourdomain.com → host)
• DNS SRV record for federation (_matrix._tcp → matrix.yourdomain.com:443)
• Docker and Docker Compose installed
• .env file configured with real values
• Ports 80, 443, 8448 open in firewall
• Run ./deploy-conduit.sh install
• Run ./deploy-conduit.sh start
• Create admin account immediately
• Disable registration in .env and restart
• Test with Element Web or other client

Account Creation (One-Time)

IMPORTANT: Only enable registration during initial admin account creation.

1. Set CONDUIT_ALLOW_REGISTRATION=true in .env
2. Set CONDUIT_REGISTRATION_TOKEN to a random secret
3. Restart: ./deploy-conduit.sh restart
4. Create account:

   ./deploy-conduit.sh admin
   # Inside container:
   register_new_matrix_user -c /var/lib/matrix-conduit -u admin -p YOUR_PASS -a
   

5. Set CONDUIT_ALLOW_REGISTRATION=false and restart

Federation Troubleshooting

Federation allows your server to communicate with other Matrix servers (matrix.org, etc).

Verify Federation Works

curl https://matrix.org/_matrix/federation/v1/query/directory?room_alias=%23timmy%3Amatrix.yourdomain.com

Required:

• DNS SRV: _matrix._tcp.yourdomain.com IN SRV 10 0 443 matrix.yourdomain.com
• Or .well-known/matrix/server served on port 443
• Port 8448 reachable (Caddy handles this)

Backup and Recovery

Automated Daily Backup (cron)

0 2 * * * /path/to/timmy-config/infra/matrix/scripts/deploy-conduit.sh backup

Restore from Backup

./deploy-conduit.sh stop
cd infra/matrix/conduit
rm -rf data/*
tar xzf /path/to/backup.tar.gz
./scripts/deploy-conduit.sh start

Monitoring

Health Endpoint

curl http://localhost:6167/_matrix/client/versions

Prometheus Metrics

Enable in .env: CONDUIT_ENABLE_METRICS=true Metrics available at: http://localhost:6167/_matrix/metrics

Federation Federation

If you don't need federation (standalone server): Set CONDUIT_ALLOW_FEDERATION=false in .env

Matrix Client Configuration

Element Web (Self-Hosted)

Create element-config.json:

{
  "default_server_config": {
    "m.homeserver": {
      "base_url": "https://matrix.yourdomain.com",
      "server_name": "yourdomain.com"
    }
  }
}

Element Desktop/Mobile

• Homeserver URL: https://matrix.yourdomain.com
• User ID: @username:yourdomain.com

Security Hardening

• Fail2ban on SSH and HTTP
• Keep Docker images updated: docker compose pull && docker compose up -d
• Review Caddy logs for abuse
• Disable registration after admin creation
• Use strong admin password
• Store backups encrypted

Related Issues

• Epic: timmy-config#166
• Scaffold: timmy-config#183
• Parent Epic: timmy-config#173 (Unified Comms)