120 lines
3.3 KiB
Markdown
120 lines
3.3 KiB
Markdown
# 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:
|
|
```bash
|
|
./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
|
|
```bash
|
|
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)
|
|
```bash
|
|
0 2 * * * /path/to/timmy-config/infra/matrix/scripts/deploy-conduit.sh backup
|
|
```
|
|
|
|
### Restore from Backup
|
|
```bash
|
|
./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
|
|
```bash
|
|
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`:
|
|
```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)
|