VuongKB/infrastructure/matrix-docker-deployment.md

---
created: '2026-04-11T08:13:34+00:00'
id: 4aebb788-2478-4fc7-9171-c3cbd25032a3
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: []
modified: '2026-04-11T08:13:34+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
---

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

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