GitHub/ess-docker-compose
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Rewrite all documentation to reflect current project state

Browse Source 
- README: add quickstart.sh as primary entry point, update deployment options
- SETUP.md: replace stale manual wizard with accurate manual config reference
- QUICK_REFERENCE.md: remove emojis/AI fluff, update compose commands, fix stale paths
- BUGFIXES.md: fix compose command references, add CVE-2025-49090, remove emojis

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
wmair
2026-03-01 14:37:09 +01:00
parent 9e42903b1f
commit e789b845cb
5 changed files with 472 additions and 1669 deletions
Download Patch File Download Diff File Expand all files Collapse all files
BRIDGE_SETUP_GUIDE.md
+4 -4
View File
@@ -539,14 +539,14 @@ docker restart matrix-bridge-telegram
### What You Get
✅ **Working**:
**Working**:
- Bridge connected to WhatsApp/Signal/Telegram
- Double puppet configured (better message attribution)
- Messages work in **unencrypted** Matrix rooms (both directions)
- Messages work in unencrypted Matrix rooms (both directions)
- Messages appear from your actual user, not bot
❌ **Not Working** (Known Issue):
- Encrypted Matrix rooms → Synapse NotImplementedError with MAS + MSC4190
**Not working** (known issue):
- Encrypted Matrix rooms — Synapse NotImplementedError with MAS + MSC4190
### Future: When MAS Appservice Login Is Supported
BUGFIXES.md
+30 -117
View File
@@ -252,9 +252,9 @@ Claims templates render to empty strings when using Authelia as the upstream pro
### Root Cause
Authelia provides different claims than expected. Testing revealed:
- ❌ `{{ user.name }}` - Not provided by Authelia
- ✅ `{{ user.preferred_username }}` - Works (contains username)
- ✅ `{{ user.email }}` - Works
- `{{ user.name }}` — not provided by Authelia
- `{{ user.preferred_username }}` — works (contains username)
- `{{ user.email }}` — works
### Solution
Use `preferred_username` for localpart and displayname:
@@ -402,45 +402,36 @@ head -2 .env
# If postgres/data is OLDER than .env, you have a mismatch!
```
### Solution 1: Clean Slate (Recommended for Testing)
### Solution 1: Clean Slate (Recommended)
```bash
# Stop all services
docker compose -f docker-compose.local.yml --profile authelia down
docker compose down
# Delete all data directories
sudo rm -rf postgres/data synapse/data mas/data mas/certs caddy/data caddy/config
# Re-run deployment
./deploy.sh
./quickstart.sh # or ./deploy.sh
```
### Solution 2: Manual Password Update (For Preserving Data)
### Solution 2: Manual Password Update (Preserves Data)
```bash
# Get the new password from .env
source .env
echo $POSTGRES_PASSWORD
# Connect to PostgreSQL
docker compose -f docker-compose.local.yml exec postgres psql -U synapse
docker compose exec postgres psql -U synapse
# Update the password
ALTER USER synapse WITH PASSWORD 'new_password_from_env';
\q
# Restart all services
docker compose -f docker-compose.local.yml --profile authelia restart
docker compose restart
```
### Prevention
The deploy script now includes a **pre-flight data directory check** that:
1. Detects existing data directories before deployment
2. Warns about potential password/config mismatches
3. Offers three options:
- **Clean slate**: Delete all data and start fresh (recommended for testing)
- **Keep data**: Continue with existing data (may cause errors)
- **Abort**: Exit and manually backup/clean data
This check runs automatically when you execute `./deploy.sh`.
Both `quickstart.sh` and `deploy.sh` detect existing data directories and warn before proceeding. `quickstart.sh` explicitly wipes `postgres/data` when the user confirms, preventing the mismatch.
### Why This Happens
- Docker volumes and bind mounts persist even after `docker compose down`
@@ -450,10 +441,10 @@ This check runs automatically when you execute `./deploy.sh`.
### Impact on All Deployment Variants
This issue affects:
- ✅ Local deployment (fixed with data directory check)
- ✅ Production deployment (fixed with data directory check)
- ✅ With Authelia (affected)
- ✅ Without Authelia (affected)
- Local deployment (fixed with data directory check)
- Production deployment (fixed with data directory check)
- With Authelia (affected)
- Without Authelia (affected)
All deployment modes now include the pre-flight check to prevent this issue.
@@ -563,10 +554,10 @@ This allows Synapse to:
### Impact on All Deployment Variants
This issue affects:
- ✅ Local deployment (fixed with IPv6 hosts entries and Synapse CA config)
- ✅ Production deployment (would need same fixes - IPv6 handled by real DNS, CA certs handled by Let's Encrypt)
- ✅ With Authelia (affected - Synapse needs to reach MAS)
- ✅ Without Authelia (affected - Synapse still needs to reach MAS)
- Local deployment (fixed with IPv6 hosts entries and Synapse CA config)
- Production deployment (would need same fixes - IPv6 handled by real DNS, CA certs handled by Let's Encrypt)
- With Authelia (affected - Synapse needs to reach MAS)
- Without Authelia (affected - Synapse still needs to reach MAS)
### Why This Happens
1. **Local Development Environment**: Uses self-signed certificates requiring explicit trust
@@ -631,59 +622,6 @@ When making changes to the stack, follow this checklist to avoid common issues:
---
## Testing Checklist
After deployment, verify each component:
### 1. Basic Connectivity
```bash
# Test all HTTPS endpoints
curl -I https://matrix.example.test
curl -I https://element.example.test
curl -I https://auth.example.test
curl -I https://authelia.example.test
# All should return HTTP 200 or appropriate redirect
```
### 2. OIDC Discovery
```bash
curl https://auth.example.test/.well-known/openid-configuration | jq
# Should return valid OIDC discovery document
```
### 3. MAS Assets
```bash
curl -I https://auth.example.test/assets/shared-CVCHz34K.css
# Should return HTTP 200
```
### 4. Matrix Well-Known
```bash
curl https://matrix.example.test/.well-known/matrix/client | jq
# Should return homeserver and authentication issuer
```
### 5. Full Authentication Flow
1. Navigate to Element: `https://element.example.test`
2. Click "Sign In"
3. Verify redirect to MAS: `https://auth.example.test`
4. Verify redirect to Authelia: `https://authelia.example.test`
5. Log in with credentials
6. Complete 2FA setup
7. Verify redirect back to Element
8. Verify successful login
### 6. Database Verification
```bash
# Check MAS provider configuration
docker compose exec postgres psql -U synapse -d mas -c \
"SELECT upstream_oauth_provider_id, fetch_userinfo, claims_imports FROM upstream_oauth_providers;"
# Verify fetch_userinfo is 't' (true)
# Verify claims_imports uses preferred_username
```
---
## Common Pitfalls
@@ -724,55 +662,30 @@ docker compose exec postgres psql -U synapse -d mas -c \
## Security Advisories
### Synapse v1.147.1 — CVE-2026-24044
### CVE-2025-49090 — Synapse room version default
Blocks federation requests using a known-compromised signing key. Pull and redeploy promptly:
Synapse versions before 1.130.0 default to room version 10, which has a known vulnerability. This stack sets the default to room version 12 in `homeserver.yaml`:
```bash
docker compose pull synapse && docker compose up -d synapse
# Verify: docker compose exec synapse synapse_homeserver --version
```yaml
default_room_version: "12"
```
The compose file uses `latest`, so this is the only action needed.
This is applied automatically by `deploy.sh` and `quickstart.sh`. If you have an existing `homeserver.yaml` generated before this fix, add the line manually and restart Synapse.
---
### Updating images
## Version-Specific Notes
The compose file uses `latest` for all images. To apply any security update:
### MAS v1.5.0
- Confirmed working with all fixes applied
- Assets must be explicitly enabled in listener resources
- `fetch_userinfo` defaults to `false`
### Authelia v4.39.13
- Rejects public suffix list domains for cookies
- Provides `preferred_username` claim, not `name`
- Requires exact redirect URI matches
- `jwt_secret` is deprecated, use `identity_validation.reset_password.jwt_secret`
### Synapse (latest)
- MSC3861 (OAuth delegation) is marked as experimental
- Works reliably with MAS when properly configured
```bash
docker compose pull
docker compose up -d
```
---
## Additional Resources
- [Public Suffix List](https://publicsuffix.org/)
- [OIDC Core Specification](https://openid.net/specs/openid-connect-core-1_0.html)
- [MAS Configuration Reference](https://element-hq.github.io/matrix-authentication-service/)
- [Authelia Configuration](https://www.authelia.com/configuration/)
---
## Contributing to This Document
If you encounter additional issues not covered here:
1. Document the problem clearly
2. Include error messages
3. Explain the root cause
4. Provide the solution
5. Note why it's not in official docs
6. Add to the appropriate section
This helps future deployments avoid the same pitfalls!
- [Synapse Configuration](https://element-hq.github.io/synapse/latest/usage/configuration/config_documentation.html)
QUICK_REFERENCE.md
+153 -332
View File
@@ -1,381 +1,202 @@
# Matrix Stack Quick Reference
Quick command reference for common operations.
## 🚀 Deployment
## Deployment
```bash
# First time deployment
chmod +x deploy.sh
# Simple production deployment (recommended for most users)
./quickstart.sh
# Advanced deployment (local testing, Authelia, multi-machine)
./deploy.sh
# During deployment, you'll be asked:
# - Deployment type (local/production)
# - Whether to include Authelia SSO (Y/n)
# Update /etc/hosts first!
sudo nano /etc/hosts
# Add (for local deployment):
# 127.0.0.1 matrix.example.test
# 127.0.0.1 element.example.test
# 127.0.0.1 auth.example.test
# 127.0.0.1 authelia.example.test (only if using Authelia)
# Set up messaging bridges (after core stack is running)
./setup-bridges.sh
```
## 🔑 Authentication Options
## Service Management
The deployment script offers two authentication modes:
```bash
# Status
docker compose ps
docker compose --profile single-machine ps # if started via quickstart.sh
docker compose --profile element-call ps # if Element Call is enabled
### With Authelia (Recommended)
- Full SSO with 2FA support
- LDAP/file-based user management
- Centralized authentication
- Includes Redis for session storage
# Start
docker compose --profile single-machine up -d
### Without Authelia (MAS Only)
- MAS handles password authentication directly
- Simpler setup for basic use cases
- No upstream OAuth provider required
- No Redis dependency
# Stop
docker compose --profile single-machine down
## 🌐 Access URLs
# Restart one service
docker compose restart synapse
docker compose restart mas
docker compose restart caddy
# Update all images
docker compose pull
docker compose --profile single-machine up -d
```
## Logs
```bash
# Follow all
docker compose logs -f
# Follow one service
docker compose logs -f synapse
docker compose logs -f mas
docker compose logs -f caddy
# Last 100 lines
docker compose logs --tail=100 synapse
# Search for errors
docker compose logs | grep -i error
```
## Access URLs (production)
| Service | URL |
|---------|-----|
| Element Web | https://element.yourdomain.com |
| Matrix API | https://matrix.yourdomain.com |
| MAS Auth | https://auth.yourdomain.com |
| Element Admin | https://admin.yourdomain.com |
| Element Call | https://call.yourdomain.com (optional) |
## Access URLs (local testing)
| Service | URL |
|---------|-----|
| Element Web | https://element.example.test |
| Matrix API | https://matrix.example.test |
| MAS Auth | https://auth.example.test |
| Authelia SSO | https://authelia.example.test |
| Caddy Admin | http://localhost:2019 |
| Element Admin | https://admin.example.test |
| Authelia | https://authelia.example.test (optional) |
## 📦 Service Management
### With Authelia
## User Management
```bash
# View all services
docker compose -f docker-compose.local.yml --profile authelia ps
# Create a user via MAS CLI
docker compose exec mas mas-cli manage register-user USERNAME
# Start all services
docker compose -f docker-compose.local.yml --profile authelia up -d
# Create an admin user
docker compose exec mas mas-cli manage register-user USERNAME --admin
# Stop all services
docker compose -f docker-compose.local.yml --profile authelia down
# Restart specific service
docker compose -f docker-compose.local.yml --profile authelia restart mas
# Restart all services
docker compose -f docker-compose.local.yml --profile authelia restart
# List users
docker compose exec mas mas-cli manage list-users
```
### Without Authelia (MAS Only)
```bash
# View all services
docker compose -f docker-compose.local.yml ps
# Start all services
docker compose -f docker-compose.local.yml up -d
# Stop all services
docker compose -f docker-compose.local.yml down
# Restart specific service
docker compose -f docker-compose.local.yml restart mas
# Restart all services
docker compose -f docker-compose.local.yml restart
```
## 📝 Logs
```bash
# Follow all logs (add --profile authelia if using Authelia)
docker compose -f docker-compose.local.yml logs -f
docker compose -f docker-compose.local.yml --profile authelia logs -f # with Authelia
# Follow specific service
docker compose -f docker-compose.local.yml logs -f mas
docker compose -f docker-compose.local.yml --profile authelia logs -f authelia # Authelia logs
# Last 100 lines
docker compose -f docker-compose.local.yml logs --tail=100 synapse
# Search logs for errors
docker compose -f docker-compose.local.yml logs mas | grep ERROR
```
## 🗄️ Database Operations
## Database
```bash
# Connect to PostgreSQL
docker compose -f docker-compose.local.yml exec postgres psql -U synapse
docker compose exec postgres psql -U synapse
# Connect to specific database
docker compose -f docker-compose.local.yml exec postgres psql -U synapse -d mas
# Connect to a specific database
docker compose exec postgres psql -U synapse -d mas
# List databases
docker compose -f docker-compose.local.yml exec postgres psql -U synapse -c "\l"
# Dump all databases
docker compose exec -T postgres pg_dumpall -U synapse > backup-$(date +%Y%m%d).sql
# MAS provider check
docker compose -f docker-compose.local.yml exec postgres psql -U synapse -d mas -c \
"SELECT upstream_oauth_provider_id, fetch_userinfo, issuer FROM upstream_oauth_providers;"
# Database sizes
docker compose exec postgres psql -U synapse -c \
"SELECT datname, pg_size_pretty(pg_database_size(datname)) FROM pg_database;"
```
## 🔧 Troubleshooting
### Fix MAS Provider Cache
## Backup
```bash
# Delete provider to force config re-sync
docker compose -f docker-compose.local.yml exec postgres psql -U synapse -d mas << 'EOF'
# Quick backup (all critical data)
tar -czf matrix-backup-$(date +%Y%m%d).tar.gz \
postgres/data synapse/data mas/data .env mas-signing.key
# Database-only dump (can run while services are up)
docker compose exec -T postgres pg_dumpall -U synapse > db-$(date +%Y%m%d).sql
```
## Verification
```bash
# Test Matrix API
curl https://matrix.yourdomain.com/_matrix/client/versions
# Test well-known
curl https://matrix.yourdomain.com/.well-known/matrix/client | jq
# Test MAS OIDC discovery
curl https://auth.yourdomain.com/.well-known/openid-configuration | jq
# Check PostgreSQL
docker compose exec postgres pg_isready -U synapse
# Check Synapse health
curl http://localhost:8008/health
```
## Troubleshooting
```bash
# Service won't start — check logs
docker compose logs --tail=50 synapse
# Force recreate a container
docker compose up -d --force-recreate synapse
# Fix MAS provider cache (after config change)
docker compose exec postgres psql -U synapse -d mas << 'EOF'
DELETE FROM upstream_oauth_authorization_sessions WHERE upstream_oauth_provider_id = (SELECT upstream_oauth_provider_id FROM upstream_oauth_providers LIMIT 1);
DELETE FROM upstream_oauth_links WHERE upstream_oauth_provider_id = (SELECT upstream_oauth_provider_id FROM upstream_oauth_providers LIMIT 1);
DELETE FROM upstream_oauth_providers;
EOF
docker compose restart mas
# Restart MAS
docker compose -f docker-compose.local.yml restart mas
```
### Extract Caddy CA Certificate
```bash
# Create certs directory
mkdir -p mas/certs
# Extract certificate
docker compose -f docker-compose.local.yml exec caddy cat \
/data/caddy/pki/authorities/local/root.crt > mas/certs/caddy-ca.crt
# Restart MAS
docker compose -f docker-compose.local.yml restart mas
```
### Check Service Health
```bash
# Check all container health
docker compose -f docker-compose.local.yml ps
# Check specific service logs for errors
docker compose -f docker-compose.local.yml logs --tail=50 mas | grep ERROR
# Test HTTPS endpoints
curl -k https://matrix.example.test/_matrix/client/versions
curl -k https://auth.example.test/.well-known/openid-configuration
curl -I -k https://auth.example.test/assets/shared-CVCHz34K.css
```
## 👤 User Management
### Add Authelia User
```bash
# Generate password hash
docker run --rm authelia/authelia:latest \
authelia crypto hash generate argon2 --password 'userpassword'
# Edit users database
nano authelia/config/users_database.yml
# Add user:
# username:
# displayname: "Full Name"
# password: "$argon2id$..."
# email: user@matrix.example.test
# groups:
# - users
# Restart Authelia
docker compose -f docker-compose.local.yml restart authelia
```
### Change Admin Password
```bash
# Generate new password hash
docker run --rm authelia/authelia:latest \
authelia crypto hash generate argon2 --password 'newpassword'
# Update authelia/config/users_database.yml
# Replace admin password hash
# Restart Authelia
docker compose -f docker-compose.local.yml restart authelia
```
## 💾 Backup & Restore
### Quick Backup
```bash
# Backup databases
docker compose -f docker-compose.local.yml exec -T postgres pg_dumpall -U synapse \
> backup_$(date +%Y%m%d).sql
# Backup configs
tar -czf config_backup_$(date +%Y%m%d).tar.gz \
authelia/config mas/config synapse/data/homeserver.yaml \
authelia_private.pem mas-signing.key .env
```
### Full Backup
```bash
# Create backup directory
mkdir -p backups/$(date +%Y%m%d)
# Backup everything
docker compose -f docker-compose.local.yml exec -T postgres pg_dumpall -U synapse \
> backups/$(date +%Y%m%d)/databases.sql
tar -czf backups/$(date +%Y%m%d)/configs.tar.gz \
authelia/config mas/config synapse/data/homeserver.yaml \
element/config authelia_private.pem mas-signing.key .env
tar -czf backups/$(date +%Y%m%d)/media.tar.gz synapse/data/media_store
```
### Restore from Backup
```bash
# Restore databases
docker compose -f docker-compose.local.yml exec -T postgres psql -U synapse < backup.sql
# Restore configs
tar -xzf configs.tar.gz
# Restart all services
docker compose -f docker-compose.local.yml restart
```
## 🔄 Updates
```bash
# Pull latest images
docker compose -f docker-compose.local.yml pull
# Recreate containers
docker compose -f docker-compose.local.yml up -d
# Remove old images
docker image prune -a
```
## 🧹 Cleanup
```bash
# Stop and remove containers (keeps data)
docker compose -f docker-compose.local.yml down
# Stop and remove everything INCLUDING DATA (⚠️ DESTRUCTIVE!)
docker compose -f docker-compose.local.yml down -v
rm -rf postgres/data synapse/data mas/data
# Remove unused Docker resources
docker system prune -a
```
## 🔍 Verification Tests
```bash
# Test Matrix API
curl -k https://matrix.example.test/_matrix/client/versions | jq
# Test Matrix well-known
curl -k https://matrix.example.test/.well-known/matrix/client | jq
# Test MAS OIDC discovery
curl -k https://auth.example.test/.well-known/openid-configuration | jq
# Test Authelia OIDC discovery
curl -k https://authelia.example.test/.well-known/openid-configuration | jq
# Test MAS assets
curl -I -k https://auth.example.test/assets/shared-CVCHz34K.css
# Check PostgreSQL health
docker compose -f docker-compose.local.yml exec postgres pg_isready -U synapse
```
## 🚨 Emergency Commands
### Services Won't Start
```bash
# Check what's failing
docker compose -f docker-compose.local.yml ps
# View logs
docker compose -f docker-compose.local.yml logs --tail=50
# Force recreate
docker compose -f docker-compose.local.yml up -d --force-recreate
# Nuclear option (stops all, removes containers, restart fresh)
docker compose -f docker-compose.local.yml down
docker compose -f docker-compose.local.yml up -d
```
### Database Issues
```bash
# Stop all services
docker compose -f docker-compose.local.yml down
# Start only PostgreSQL
docker compose -f docker-compose.local.yml up -d postgres
# Wait and check
sleep 10
docker compose -f docker-compose.local.yml logs postgres
# If working, start everything else
docker compose -f docker-compose.local.yml up -d
```
### Port Conflicts
```bash
# Find what's using port 443
# Port conflict — find what's using the port
sudo lsof -i :443
sudo lsof -i :8008
# Kill process if needed
sudo kill -9 <PID>
# Or change ports in docker-compose.local.yml
nano docker-compose.local.yml
# Change "443:443" to "8443:443"
# Find all matrix containers
docker ps --filter name=matrix
```
## 📚 Documentation Quick Links
## Bridge Operations
- **[DEPLOYMENT_GUIDE.md](DEPLOYMENT_GUIDE.md)** - Complete deployment guide
- **[BUGFIXES.md](BUGFIXES.md)** - Critical fixes and troubleshooting
- **[README.md](README.md)** - Quick start overview
- **[PRODUCTION.md](PRODUCTION.md)** - Production deployment guide
```bash
# Bridge status
docker compose logs --tail=30 mautrix-whatsapp
docker compose logs --tail=30 mautrix-signal
docker compose logs --tail=30 mautrix-telegram
## 🆘 Common Error Solutions
# Restart a bridge
docker compose restart mautrix-whatsapp
# Full bridge setup (run after core stack is running)
./setup-bridges.sh
```
## Local Testing (extra steps)
```bash
# Add to /etc/hosts (both IPv4 and IPv6 required)
echo "127.0.0.1 matrix.example.test element.example.test auth.example.test authelia.example.test" | sudo tee -a /etc/hosts
echo "::1 matrix.example.test element.example.test auth.example.test authelia.example.test" | sudo tee -a /etc/hosts
# Test with self-signed cert
curl -k https://matrix.example.test/_matrix/client/versions
# Extract Caddy CA cert (if MAS can't connect to auth domain)
cp caddy/data/caddy/pki/authorities/local/root.crt mas/certs/caddy-ca.crt
docker compose restart mas
```
## Common Error Fixes
| Error | Fix |
|-------|-----|
| CSS not loading | Check MAS has `assets` resource, restart MAS |
| Empty string template error | Verify `fetch_userinfo: true`, delete provider from DB |
| Redirect URI mismatch | Add all redirect URIs to Authelia config |
| Cookie domain error | Use `example.test` not `.localhost` |
| SSL certificate error | Extract Caddy CA cert, mount in MAS |
| Database connection failed | Restart postgres first, wait, then start others |
## 📞 Getting Help
1. Check service logs: `docker compose logs -f service-name`
2. Review [BUGFIXES.md](BUGFIXES.md) for detailed solutions
3. Run validation: `./validate-setup.sh`
4. Check database state with queries above
5. Try clean restart: `down` then `up -d`
---
**💡 Tip:** Bookmark this page for quick access to common commands!
| `password authentication failed` | postgres/data exists with old password — wipe and redeploy |
| `homeserver.domain not configured` (bridge) | Run `setup-bridges.sh` |
| `as_token was not accepted` | Registration not loaded in Synapse — check `homeserver.yaml` |
| MAS CSS missing | Add `- name: assets` to MAS listener resources |
| `Template rendered to empty string` | Set `fetch_userinfo: true` in MAS upstream provider |
| Bridge: `Connection refused` | Bridge hostname is 127.0.0.1 — must be 0.0.0.0 in config |
README.md
+32 -17
View File
@@ -23,16 +23,24 @@ A self-hosted Matrix server stack with modern OIDC authentication, web client, o
- [mautrix-telegram](https://github.com/mautrix/telegram) — Telegram bridge (requires API credentials)
**Optional: Upstream OIDC** (`--profile authelia`)
- [Authelia](https://www.authelia.com/) — SSO / identity provider
- [Authelia](https://www.authelia.com/) — SSO / identity provider with 2FA
## Quick Start
**Simple production deployment** — three prompts, everything else is automatic:
```bash
./quickstart.sh
```
Asks for: your domain, a Let's Encrypt email, and whether to enable Element Call. Generates all secrets and configs, starts the stack.
**Advanced deployment** — local testing, Authelia SSO, multi-machine setups:
```bash
./deploy.sh
```
The script handles everything interactively: generates secrets, writes configs, starts Docker services. It asks whether to enable Element Call and optionally Authelia.
Bridges are set up separately after the core stack is running:
```bash
@@ -47,7 +55,7 @@ Browser
Caddy (HTTPS, Let's Encrypt)
|
+-- matrix.example.com --> Synapse :8008
| /.well-known --> (inline, served by Caddy)
| /.well-known --> (served inline by Caddy)
| /login, /logout --> MAS :8080
+-- auth.example.com --> MAS :8080
+-- element.example.com --> Element Web :80
@@ -61,27 +69,32 @@ All services communicate over an internal Docker network. The database is not ex
## Deployment Options
**Local testing** — self-signed certificates, all services on localhost:
**Simple production** — single machine, Let's Encrypt, no Authelia:
```bash
docker compose -f docker-compose.yml -f compose-variants/docker-compose.local.yml up -d
./quickstart.sh
```
**Single server** — production with Caddy on the same machine:
**Local testing** — self-signed certificates, `*.example.test` domains:
```bash
./deploy.sh # choose "single server" mode
./deploy.sh # choose "Local Testing"
```
**Multi-server** — Matrix backend on one machine, Caddy on another:
**Production with Authelia** — SSO, 2FA, upstream OIDC:
```bash
./deploy.sh # choose "multi server" mode
./deploy.sh # choose "Production", answer yes to Authelia
```
The script generates a `caddy/Caddyfile.production` for the Caddy machine.
**Multi-machine** — Matrix backend on one server, Caddy on another:
```bash
./deploy.sh # choose "Production" (multi-server mode)
```
Generates a `caddy/Caddyfile.production` for the Caddy machine.
## Element Call
When enabled, all three components are self-hosted. Media streams never leave your server (they route through your LiveKit SFU). The Element Call frontend is served from your own `call.` subdomain instead of `call.element.io`.
When enabled, all three components are self-hosted. Media streams never leave your server (they route through your LiveKit SFU). The Element Call frontend is served from your own `call.` subdomain.
Required open ports for LiveKit:
Required open ports in addition to 80 and 443:
- TCP 7881 (WebRTC signaling)
- UDP 50100–50200 (media streams)
@@ -94,7 +107,7 @@ TELEGRAM_API_ID=your_id
TELEGRAM_API_HASH=your_hash
```
Bridges use double puppet support (users in Matrix rooms appear as themselves, not the bridge bot) and have encryption disabled for compatibility with MAS.
Bridges use double puppet support (messages appear from your actual Matrix user, not a bridge bot) and have encryption disabled for compatibility with MAS. See [BRIDGE_SETUP_GUIDE.md](BRIDGE_SETUP_GUIDE.md) for details.
## Requirements
@@ -125,7 +138,7 @@ docker compose logs mautrix-whatsapp
## Data Directories
```
postgres/data/ database
postgres/data/ database (back this up)
synapse/data/ media store, signing keys
mas/data/ MAS sessions
.env all secrets and domain config
@@ -138,9 +151,11 @@ tar -czf matrix-backup-$(date +%Y%m%d).tar.gz postgres/data synapse/data mas/dat
## Documentation
- [SETUP.md](SETUP.md) — manual setup reference
- [PRODUCTION_DEPLOYMENT.md](PRODUCTION_DEPLOYMENT.md) — production checklist
- [SETUP.md](SETUP.md) — manual configuration reference
- [PRODUCTION_DEPLOYMENT.md](PRODUCTION_DEPLOYMENT.md) — production checklist and hardening
- [BRIDGE_SETUP_GUIDE.md](BRIDGE_SETUP_GUIDE.md) — bridge configuration details
- [BUGFIXES.md](BUGFIXES.md) — known issues and their solutions
- [QUICK_REFERENCE.md](QUICK_REFERENCE.md) — common commands
## License
SETUP.md
+253 -1199
View File
File diff suppressed because it is too large Load Diff