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
TLS certificate (Let's Encrypt)	sudo certbot certificates	⬜
Docker + docker-compose	docker --version	⬜

Quickstart

1. Host Preparation

# 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

sudo certbot certonly --standalone -d matrix.fleet.tld

4. Deploy Conduit

# 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

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

# 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

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

# 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