# Matrix Synapse + PostgreSQL + Element

> Federated messaging with Element web client.

- Category: Message Queues & Brokers
- Difficulty: advanced
- Components: synapse, postgresql, element-web, nginx, coturn
- Tags: matrix, synapse, element, federation, e2ee
- Source: https://docker.recipes/messaging/matrix-synapse-complete

## Overview

Matrix Synapse is an open-source reference implementation of the Matrix protocol, a decentralized communication standard that enables federated messaging, voice, and video calls across different servers and clients. Developed by the Matrix.org Foundation, Synapse serves as a homeserver that stores user accounts, room data, and message history while facilitating federation with other Matrix servers worldwide. This creates a truly distributed communication network where users can communicate across organizational boundaries without relying on centralized platforms. This comprehensive stack combines Synapse with PostgreSQL for robust data persistence, Element Web as a modern React-based client interface, NGINX for SSL termination and federation proxy, and Coturn for NAT traversal in voice/video calls. PostgreSQL provides ACID-compliant storage for Matrix's complex relational data including user accounts, room memberships, message threading, and encryption keys, while Element Web offers end-to-end encryption, file sharing, voice/video calling, and rich media support through a familiar chat interface. Organizations seeking communication sovereignty will find this stack invaluable for maintaining control over their messaging infrastructure while participating in the broader Matrix federation. The combination supports everything from small team chat to large-scale enterprise communication, with built-in encryption ensuring privacy and the federation capability enabling secure communication with external Matrix servers, making it ideal for privacy-conscious organizations, educational institutions, and government agencies requiring auditable, self-hosted communication solutions.

## Features

- End-to-end encryption for all messages, files, and voice/video calls using Matrix's Olm and Megolm cryptographic protocols
- Federation support allowing communication with users on other Matrix homeservers across the internet
- PostgreSQL backend with optimized schemas for Matrix's event-sourced architecture and efficient message retrieval
- Element Web client with support for threads, spaces, reactions, file sharing, and screen sharing
- TURN/STUN server via Coturn for reliable voice and video calls behind NAT and firewalls
- Admin API for user management, room administration, and server statistics through Synapse's REST endpoints
- Presence and typing indicators with configurable federation policies for privacy control
- Room aliases and directory services for easy room discovery and memorable addresses

## Use cases

- Enterprise internal communication requiring data sovereignty and compliance with regulations like GDPR or HIPAA
- Educational institutions needing secure student-faculty communication with administrative oversight capabilities
- Open source projects requiring persistent chat history and integration with development workflows
- Healthcare organizations needing encrypted messaging that maintains audit trails for patient communication
- Government agencies requiring secure inter-departmental communication with controlled external federation
- Remote teams needing voice/video calling with message persistence across different time zones
- Community servers for gaming guilds, hobby groups, or local organizations with custom moderation policies

## Prerequisites

- Minimum 2GB RAM for the full stack, with 4GB+ recommended for active usage and message history retention
- Domain name with DNS control for federation setup and SSL certificate management
- Ports 80, 443, 8448, 3478, and 5349 available and properly forwarded for web access, federation, and TURN services
- Basic understanding of Matrix concepts including homeservers, federation, and room structures
- SSL certificates configured in NGINX for HTTPS termination and Matrix federation over port 8448
- Understanding of PostgreSQL backup procedures for message history and user data preservation

## docker-compose.yml

```yaml
services:
  synapse:
    image: matrixdotorg/synapse:latest
    environment:
      - SYNAPSE_CONFIG_DIR=/data
      - SYNAPSE_DATA_DIR=/data
      - SYNAPSE_SERVER_NAME=${SERVER_NAME}
      - SYNAPSE_REPORT_STATS=no
    volumes:
      - synapse-data:/data
    ports:
      - "8008:8008"
    depends_on:
      - postgres
    networks:
      - matrix-network
    restart: unless-stopped

  postgres:
    image: postgres:15
    environment:
      - POSTGRES_USER=synapse
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - POSTGRES_DB=synapse
      - POSTGRES_INITDB_ARGS=--encoding=UTF-8 --lc-collate=C --lc-ctype=C
    volumes:
      - postgres-data:/var/lib/postgresql/data
    networks:
      - matrix-network
    restart: unless-stopped

  element:
    image: vectorim/element-web:latest
    volumes:
      - ./element-config.json:/app/config.json:ro
    ports:
      - "80:80"
    depends_on:
      - synapse
    networks:
      - matrix-network
    restart: unless-stopped

  coturn:
    image: coturn/coturn:latest
    environment:
      - DETECT_EXTERNAL_IP=yes
      - DETECT_RELAY_IP=yes
    volumes:
      - ./turnserver.conf:/etc/coturn/turnserver.conf:ro
    ports:
      - "3478:3478/tcp"
      - "3478:3478/udp"
      - "5349:5349/tcp"
      - "5349:5349/udp"
    networks:
      - matrix-network
    restart: unless-stopped

  nginx:
    image: nginx:alpine
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    ports:
      - "443:443"
      - "8448:8448"
    depends_on:
      - synapse
      - element
    networks:
      - matrix-network
    restart: unless-stopped

volumes:
  synapse-data:
  postgres-data:

networks:
  matrix-network:
    driver: bridge
```

## .env

```bash
# Matrix Synapse
SERVER_NAME=localhost
POSTGRES_PASSWORD=secure_postgres_password

# Generate config first:
# docker run --rm -v synapse-data:/data -e SYNAPSE_SERVER_NAME=localhost matrixdotorg/synapse:latest generate
```

## Usage notes

- Element at http://localhost
- Synapse at http://localhost:8008
- Federation on port 8448
- Generate config before first run
- COTURN for voice/video calls

## Troubleshooting

- Federation not working with other servers: Verify port 8448 is accessible externally and SSL certificates are valid for the server name
- Element shows 'Unable to connect to homeserver': Check that NGINX is properly proxying to Synapse on port 8008 and CORS headers are configured
- Voice/video calls failing to connect: Ensure Coturn is accessible on ports 3478/5349 and external IP detection is working correctly
- Database connection errors on startup: Verify PostgreSQL is fully initialized before Synapse starts, may need to add health checks or startup delays
- High memory usage in Synapse: Configure message retention policies and enable message history purging in homeserver.yaml
- Users unable to join federated rooms: Check that your server's signing keys are published correctly and DNS SRV records are configured for federation

