timmy-config/docs/matrix-conduit/DEPLOYMENT.md

# 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    <YOUR_SERVER_IP>

# 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