wmair
8cb92b9226
This is a clean, ready-to-deploy Matrix communication stack with: Features: - Matrix Synapse homeserver with PostgreSQL - Element Web client - Matrix Authentication Service (MAS) with OIDC - Authelia SSO with 2FA support - Caddy reverse proxy with automatic HTTPS - Bridges: Telegram, WhatsApp, Signal (pre-configured) Deployment Modes: - Local testing (all-in-one with self-signed certs) - Production (distributed 3-machine setup with Let's Encrypt) All Critical Bugfixes Applied: 1. Using example.test domains (not .localhost - public suffix list issue) 2. MAS assets resource enabled (fixes CSS 404 errors) 3. MAS fetch_userinfo enabled (required for Authelia claims) 4. Internal discovery URL for faster OIDC metadata fetching 5. Claims templates using preferred_username (Authelia compatible) 6. All redirect URIs configured in Authelia 7. Caddy CA certificate extraction automated 8. Correct email domains throughout Security: - All secrets generated dynamically on deployment - Cryptographically secure random generation (OpenSSL) - 4096-bit RSA keys for OIDC/JWT signing - Argon2 password hashing - No hardcoded secrets in repository Documentation: - BUGFIXES.md - Comprehensive troubleshooting guide - DEPLOYMENT_GUIDE.md - Step-by-step deployment manual - QUICK_REFERENCE.md - Command cheatsheet - README.md - Quick start guide - PRODUCTION.md - Production deployment guide Deployment: - Single command: ./deploy.sh - Fully automated configuration generation - ~10 minutes to complete setup State: Clean slate, ready for validation deployment
3.1 KiB
3.1 KiB
Setup Checklist
Use this checklist to track your setup progress.
Initial Setup
- Edit
.envfile with secure passwords and secrets - Generate secrets:
openssl rand -base64 32(do this 4 times for different secrets) - Set your domain name in
.env(or keepmatrix.localhostfor local testing)
Synapse Setup
- Run
./setup-synapse.shto generate Synapse config - Edit
./synapse/data/homeserver.yaml:- Configure PostgreSQL database connection
- Set
enable_registrationas desired - Add MAS experimental features (msc3861)
- Set
server_nameto your domain
Authelia Setup
- Generate password hash:
docker run authelia/authelia:latest authelia crypto hash generate argon2 --password 'yourpassword' - Update
./authelia/config/users_database.ymlwith password hash - Generate RSA key:
openssl genrsa -out authelia_private.pem 4096 - Copy RSA key to
./authelia/config/configuration.yml - Generate client secret:
docker run authelia/authelia:latest authelia crypto hash generate pbkdf2 --variant sha512 --random --random.length 72 --random.charset rfc3986 - Update client secret in both Authelia and MAS configs
MAS Setup
- Generate MAS signing key:
openssl genrsa 4096 | openssl pkcs8 -topk8 -nocrypt > mas-signing.key - Copy signing key to
./mas/config/config.yaml - Update database password in
./mas/config/config.yaml - Update client secret to match Authelia
Start Services
- Start PostgreSQL:
docker compose up -d postgres - Wait for PostgreSQL to be ready (check logs)
- Start all services:
docker compose up -d - Check all services are running:
docker compose ps - Check logs for errors:
docker compose logs
Test Basic Functionality
- Access Element Web at http://localhost:8080
- Try to sign in (should redirect through MAS → Authelia)
- Complete 2FA setup in Authelia
- Successfully log into Element
- Create a room
- Send a test message
Bridge Setup (Optional)
- Run
./setup-bridges.shto generate bridge configs - Edit each bridge config at
./bridges/{bridge}/config/config.yaml - Copy registration files to synapse data directory
- Add registration files to
homeserver.yaml - Restart Synapse:
docker compose restart synapse
Test Bridges
- Telegram: Start chat with
@telegrambot:matrix.localhost, sendlogin - WhatsApp: Start chat with
@whatsappbot:matrix.localhost, sendlogin - Signal: Start chat with
@signalbot:matrix.localhost, sendlink
Production Readiness (When Moving to Production)
- Set up reverse proxy (Caddy/nginx) with HTTPS
- Configure real domain names
- Update all URLs to use HTTPS and real domains
- Set up email server for Authelia notifications
- Configure firewall rules
- Set up automated backups
- Review security settings in all configs
- Test from external network
- Set up monitoring/alerting
- Document your specific configuration
Notes
Write any issues or notes here:
[Your notes]