332 lines
10 KiB
Markdown
332 lines
10 KiB
Markdown
---
|
|
created: '2026-04-11T08:13:34+00:00'
|
|
id: 4aebb788-2478-4fc7-9171-c3cbd25032a3
|
|
keywords:
|
|
- docker
|
|
- matrix
|
|
- synapse
|
|
- deployment
|
|
- reference
|
|
- https
|
|
- matrix.yourdomain.com
|
|
- federation
|
|
- compose
|
|
- github.com
|
|
- data
|
|
- yourdomain.com
|
|
- homeserver.yaml
|
|
- element
|
|
- matrix.org
|
|
links: []
|
|
modified: '2026-04-11T16:30:23+00:00'
|
|
summary: Comprehensive reference covering the Matrix messaging protocol, key concepts
|
|
(homeservers, federation, rooms, bridges), Synapse configuration, and a full Docker
|
|
Compose deployment guide including PostgreSQL, Element Web, federation setup, TLS/reverse
|
|
proxy notes, and backup procedures.
|
|
tags:
|
|
- infrastructure
|
|
- matrix
|
|
- docker
|
|
- self-hosted
|
|
- communication
|
|
- reference
|
|
title: Matrix — Overview & Docker Deployment Reference
|
|
---
|
|
|
|
---
|
|
id: 4aebb788-2478-4fc7-9171-c3cbd25032a3
|
|
title: "Matrix — Overview & Docker Deployment Reference"
|
|
summary: "Comprehensive reference covering the Matrix messaging protocol, key concepts (homeservers, federation, rooms, bridges), Synapse configuration, and a full Docker Compose deployment guide including PostgreSQL, Element Web, federation setup, TLS/reverse proxy notes, and backup procedures."
|
|
tags: ["infrastructure", "matrix", "docker", "self-hosted", "communication", "reference"]
|
|
keywords: ["matrix", "synapse", "element", "docker", "docker compose", "chat protocol", "federation", "homeserver", "postgresql", "decentralized communication", "end-to-end encryption", "bridges", "well-known", "matrix.org", "element-hq"]
|
|
links: []
|
|
created: 2026-04-11T08:13:34+00:00
|
|
modified: 2026-04-11T08:13:34+00:00
|
|
path: infrastructure/matrix-docker-deployment.md
|
|
---
|
|
|
|
# Matrix — Overview & Docker Deployment Reference
|
|
|
|
## What is Matrix?
|
|
|
|
Matrix is an **open standard and communication protocol** for real-time, decentralized communication. It provides end-to-end encryption, federation between servers (similar to email), and rich features like voice/video calls, bridging to other platforms (Slack, Discord, Telegram, WhatsApp, Signal, IRC, etc.), and rich media sharing.
|
|
|
|
- **Official site**: https://matrix.org
|
|
- **Specification**: https://spec.matrix.org/latest/
|
|
- **License**: Apache 2.0 (per-server implementations vary)
|
|
- **Note**: As of Synapse v1.99, Synapse is now maintained by **Element** (github.com/element-hq/synapse) rather than the Matrix.org Foundation, under a new licence.
|
|
|
|
### VM 102 Specific Deployment
|
|
|
|
For the concrete deployment on VM 102 (PFI-ANA-Docker, `10.250.50.70`) with actual IPs, compose files, storage paths, and port assignments, see: [VM 102 — Matrix Synapse Deployment](vm-102-matrix-synapse.md) and [VM 102 — Matrix Appservice Configuration](vm-102-matrix-appservice.md).
|
|
|
|
## Key Concepts
|
|
|
|
| Concept | Description |
|
|
|---|---|
|
|
| **Homeserver** | Stores communication history and account data for its users. The reference implementation is **Synapse** (Python/Twisted). Alternatives include **Dendrite** (Go) and **Conduit** (Rust). |
|
|
| **Client** | Apps that connect to a homeserver. The most popular is **Element** (web, desktop, mobile). Others include Cinny, FluffyChat, Hydrogen, SchildiChat. |
|
|
| **Federation** | Homeservers sync data with each other, allowing users on different servers to communicate (like email). Requires proper DNS and TLS configuration. |
|
|
| **Room** | A virtual space for communication. Events (messages, state changes) are emitted in the context of rooms. |
|
|
| **User ID format** | `@username:server_name` (e.g., `@alice:example.com`) |
|
|
| **Bridges** | Services that connect Matrix rooms to external platforms (Discord, Slack, Telegram, WhatsApp, IRC, etc.) |
|
|
|
|
## Synapse (Reference Homeserver)
|
|
|
|
- **Language**: Python/Twisted
|
|
- **Database**: SQLite (testing only), **PostgreSQL** (recommended for production)
|
|
- **RAM**: At least 1GB free RAM; 2GB+ recommended
|
|
- **Ports**: 8008 (Client & Federation HTTP API), 8448 (Federation HTTPS — typically via reverse proxy)
|
|
- **Official Docker image**: `matrixdotorg/synapse` (Docker Hub) or `ghcr.io/matrix-org/synapse` (GHCR)
|
|
- **GitHub**: https://github.com/matrix-org/synapse (historical) → https://github.com/element-hq/synapse (current)
|
|
|
|
## Docker Deployment Guide
|
|
|
|
### Prerequisites
|
|
|
|
- Docker Engine 20.10+
|
|
- Docker Compose v2
|
|
- A domain name (required for federation)
|
|
- At least 2GB RAM
|
|
- Ports 80, 443, and 8448 available
|
|
|
|
### Step 1: Generate Synapse Configuration
|
|
|
|
```
|
|
mkdir matrix-docker && cd matrix-docker
|
|
|
|
docker run -it --rm \
|
|
-v $(pwd)/synapse-data:/data \
|
|
-e SYNAPSE_SERVER_NAME=yourdomain.com \
|
|
-e SYNAPSE_REPORT_STATS=no \
|
|
matrixdotorg/synapse:latest generate
|
|
```
|
|
|
|
This creates `homeserver.yaml` in the `synapse-data/` directory.
|
|
|
|
### Step 2: Configure PostgreSQL in homeserver.yaml
|
|
|
|
Edit `synapse-data/homeserver.yaml`:
|
|
|
|
```yaml
|
|
server_name: "yourdomain.com"
|
|
|
|
listeners:
|
|
- port: 8008
|
|
tls: false
|
|
type: http
|
|
x_forwarded: true
|
|
resources:
|
|
- names: [client, federation]
|
|
compress: false
|
|
|
|
database:
|
|
name: psycopg2
|
|
args:
|
|
user: synapse
|
|
password: synapse_db_pass
|
|
database: synapse
|
|
host: postgres
|
|
port: 5432
|
|
cp_min: 5
|
|
cp_max: 10
|
|
|
|
media_store_path: /data/media_store
|
|
max_upload_size: 50M
|
|
|
|
enable_registration: false
|
|
report_stats: false
|
|
```
|
|
|
|
### Step 3: Docker Compose File
|
|
|
|
```yaml
|
|
version: "3.8"
|
|
|
|
services:
|
|
synapse:
|
|
image: matrixdotorg/synapse:latest
|
|
container_name: synapse
|
|
volumes:
|
|
- synapse-data:/data
|
|
environment:
|
|
SYNAPSE_CONFIG_DIR: /data
|
|
SYNAPSE_CONFIG_PATH: /data/homeserver.yaml
|
|
TZ: "UTC"
|
|
depends_on:
|
|
postgres:
|
|
condition: service_healthy
|
|
ports:
|
|
- "8008:8008"
|
|
- "8448:8448"
|
|
networks:
|
|
- matrix-network
|
|
restart: unless-stopped
|
|
|
|
postgres:
|
|
image: postgres:16-alpine
|
|
container_name: synapse-postgres
|
|
environment:
|
|
POSTGRES_DB: synapse
|
|
POSTGRES_USER: synapse
|
|
POSTGRES_PASSWORD: synapse_db_pass
|
|
POSTGRES_INITDB_ARGS: "--encoding=UTF-8 --lc-collate=C --lc-ctype=C"
|
|
volumes:
|
|
- postgres-data:/var/lib/postgresql/data
|
|
healthcheck:
|
|
test: ["CMD-SHELL", "pg_isready -U synapse"]
|
|
interval: 5s
|
|
timeout: 5s
|
|
retries: 10
|
|
networks:
|
|
- matrix-network
|
|
restart: unless-stopped
|
|
|
|
element:
|
|
image: vectorim/element-web:latest
|
|
container_name: element-web
|
|
volumes:
|
|
- ./element-config.json:/app/config.json:ro
|
|
ports:
|
|
- "8080:80"
|
|
networks:
|
|
- matrix-network
|
|
restart: unless-stopped
|
|
|
|
volumes:
|
|
synapse-data:
|
|
postgres-data:
|
|
|
|
networks:
|
|
matrix-network:
|
|
driver: bridge
|
|
```
|
|
|
|
### Step 4: Element Configuration
|
|
|
|
Create `element-config.json`:
|
|
|
|
```json
|
|
{
|
|
"default_server_config": {
|
|
"m.homeserver": {
|
|
"base_url": "https://matrix.yourdomain.com",
|
|
"server_name": "yourdomain.com"
|
|
},
|
|
"m.identity_server": {
|
|
"base_url": "https://vector.im"
|
|
}
|
|
},
|
|
"brand": "Element",
|
|
"room_directory": {
|
|
"servers": ["yourdomain.com", "matrix.org"]
|
|
}
|
|
}
|
|
```
|
|
|
|
### Step 5: Federation — .well-known Files
|
|
|
|
```
|
|
mkdir -p well-known/matrix
|
|
|
|
# well-known/matrix/server
|
|
{"m.server": "matrix.yourdomain.com:443"}
|
|
|
|
# well-known/matrix/client
|
|
{"m.homeserver": {"base_url": "https://matrix.yourdomain.com"}}
|
|
```
|
|
|
|
### Step 6: DNS Records
|
|
|
|
```
|
|
matrix.yourdomain.com A YOUR_SERVER_IP
|
|
element.yourdomain.com A YOUR_SERVER_IP
|
|
```
|
|
|
|
### Step 7: Start Services
|
|
|
|
```
|
|
docker compose up -d postgres
|
|
docker compose up -d synapse
|
|
docker compose up -d element
|
|
```
|
|
|
|
### Step 8: Create Admin User
|
|
|
|
```
|
|
docker exec -it synapse register_new_matrix_user \
|
|
http://localhost:8008 \
|
|
-c /data/homeserver.yaml \
|
|
-u admin \
|
|
-p SECURE_PASSWORD \
|
|
--admin
|
|
```
|
|
|
|
### TLS / Reverse Proxy
|
|
|
|
For production, put Nginx or Traefik in front of Synapse with TLS termination. Key points:
|
|
- Port 443: Client-Server API and Federation (with `x_forwarded: true` in Synapse)
|
|
- Port 8448: Dedicated Federation port (required for some federation scenarios)
|
|
- Client max body size: at least 50M for media uploads
|
|
- `.well-known/matrix/server` and `.well-known/matrix/client` must be served with `Access-Control-Allow-Origin: *`
|
|
|
|
## Alternative Homeservers
|
|
|
|
| Homeserver | Language | Notes |
|
|
|---|---|---|
|
|
| **Synapse** | Python/Twisted | Reference implementation, most feature-complete, heaviest resource usage |
|
|
| **Dendrite** | Go | Second-generation, lighter weight, not all features implemented |
|
|
| **Conduit** | Rust | Very lightweight, good for small deployments, still maturing |
|
|
|
|
## Community Ansible Playbook (Advanced)
|
|
|
|
For a comprehensive, production-ready setup with many services pre-configured:
|
|
|
|
- **Repository**: https://github.com/spantaleev/matrix-docker-ansible-deploy
|
|
- **Includes**: Synapse/Dendrite/Conduit, Element, PostgreSQL, Traefik, Let's Encrypt, coturn (STUN/TURN), email, 20+ bridges (Discord, Slack, Telegram, WhatsApp, Signal, IRC, etc.), bots (Mjolnir, Draupnir, reminder bot), monitoring (Prometheus/Grafana), backups (Borg), and more
|
|
- **Support room**: `#matrix-docker-ansible-deploy:devture.com`
|
|
|
|
## Useful Admin API Commands
|
|
|
|
```
|
|
# Get server version
|
|
curl -s "https://matrix.yourdomain.com/_synapse/admin/v1/server_version" \
|
|
-H "Authorization: Bearer TOKEN"
|
|
|
|
# List users
|
|
curl -s "https://matrix.yourdomain.com/_synapse/admin/v2/users?from=0&limit=10" \
|
|
-H "Authorization: Bearer TOKEN"
|
|
|
|
# Deactivate a user
|
|
curl -X POST "https://matrix.yourdomain.com/_synapse/admin/v1/deactivate/@user:yourdomain.com" \
|
|
-H "Authorization: Bearer TOKEN" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"erase": false}'
|
|
```
|
|
|
|
## Backup & Update
|
|
|
|
```bash
|
|
# Backup database
|
|
docker compose exec postgres pg_dump -U synapse synapse > backup.sql
|
|
|
|
# Backup media
|
|
docker cp synapse:/data/media_store ./media-backup
|
|
|
|
# Update
|
|
docker compose pull
|
|
docker compose up -d
|
|
```
|
|
|
|
## Sources
|
|
|
|
- Official Synapse Installation Docs: https://matrix-org.github.io/synapse/latest/setup/installation.html
|
|
- Official Docker Image (Docker Hub): https://hub.docker.com/r/matrixdotorg/synapse
|
|
- Matrix Spec: https://spec.matrix.org/latest/
|
|
- Matrix-docker-ansible-deploy: https://github.com/spantaleev/matrix-docker-ansible-deploy
|
|
- OneUptime Docker Guide: https://oneuptime.com/blog/post/2026-02-08-how-to-run-matrix-synapse-in-docker-for-chat/view
|
|
- Docker Recipes (ready-to-deploy): https://docker.recipes/productivity/matrix-synapse-stack
|
|
- Matrix Protocol (Wikipedia): https://en.wikipedia.org/wiki/Matrix_(protocol)
|
|
- Medium Docker Compose Guide: https://medium.com/@sncr28/deploying-a-matrix-server-with-element-chat-in-docker-compose-with-nginx-reverse-proxy-cc9850fd32f8
|
|
|
|
(Date of research: April 2026) |