# Element + Matrix Homeserver

> Decentralized communication with Matrix Synapse and Element web client.

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

## Overview

Matrix Synapse is the reference implementation of the Matrix protocol, an open standard for secure, decentralized real-time communication. Developed by the Matrix.org Foundation, Synapse serves as a homeserver that enables federation with other Matrix servers worldwide, creating a distributed network where users maintain control over their data while communicating across server boundaries. This architecture eliminates single points of failure and vendor lock-in common in centralized messaging platforms.

This stack combines Synapse with Element Web (formerly Riot), the flagship Matrix client that provides a modern web interface for messaging, voice, and video calls. PostgreSQL serves as the primary database for storing room state, user data, and message history with ACID compliance ensuring data integrity during concurrent operations. Redis handles session caching and worker coordination for horizontal scaling, while Coturn provides TURN/STUN services essential for voice and video calls behind NAT firewalls. Nginx acts as a reverse proxy, handling SSL termination and routing federation traffic.

Organizations seeking to deploy private, self-hosted communication infrastructure will find this stack particularly valuable. Unlike centralized services, Matrix federation allows internal users to communicate with external Matrix servers while maintaining control over sensitive data. The combination of Synapse's robust server implementation with Element's polished interface creates a production-ready alternative to platforms like Slack or Microsoft Teams, with the added benefit of end-to-end encryption by default and compliance with data sovereignty requirements.

## Features

- Matrix protocol federation enabling communication across different homeservers
- End-to-end encryption for messages, voice calls, and video calls using Olm/Megolm cryptographic ratchets
- PostgreSQL backend with optimized schema for Matrix's directed acyclic graph room structure
- Redis-powered worker mode supporting horizontal scaling across multiple Synapse processes
- Coturn TURN/STUN server for WebRTC voice and video calls through NAT firewalls
- Element Web client with real-time synchronization, message threading, and rich media support
- Server-side room directory and user discovery with configurable federation policies
- Application service integration allowing bridges to IRC, Discord, Telegram, and other platforms

## Use cases

- Enterprise internal communication with end-to-end encryption compliance requirements
- Educational institutions requiring FERPA-compliant messaging with external collaboration
- Healthcare organizations needing HIPAA-compliant communication infrastructure
- Government agencies requiring sovereign control over communication data
- Open source projects wanting community chat with IRC/Discord bridge integration
- Privacy-focused organizations migrating from centralized platforms like Slack or Teams
- International companies needing federated communication across regional data boundaries

## Prerequisites

- Minimum 2GB RAM (PostgreSQL requires 1GB+, Synapse 512MB+ for small deployments)
- Valid domain name with DNS control for Matrix federation on port 8448
- SSL certificate authority access or Let's Encrypt compatibility for HTTPS
- Understanding of Matrix protocol concepts including homeservers, rooms, and federation
- Network firewall configuration allowing ports 80, 443, 8448, and 3478-5349 range
- Basic knowledge of reverse proxy configuration for Element Web and Synapse integration

## docker-compose.yml

```yaml
services:
  postgres:
    image: postgres:15-alpine
    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_net

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data
    networks:
      - matrix_net

  synapse:
    image: matrixdotorg/synapse:latest
    environment:
      - SYNAPSE_SERVER_NAME=localhost
      - SYNAPSE_REPORT_STATS=no
    volumes:
      - synapse_data:/data
    depends_on:
      - postgres
      - redis
    ports:
      - "8008:8008"
      - "8448:8448"
    networks:
      - matrix_net

  element-web:
    image: vectorim/element-web:latest
    ports:
      - "8080:80"
    volumes:
      - ./element-config.json:/app/config.json:ro
    depends_on:
      - synapse
    networks:
      - matrix_net

  coturn:
    image: coturn/coturn:latest
    ports:
      - "3478:3478"
      - "3478:3478/udp"
      - "5349:5349"
      - "5349:5349/udp"
    environment:
      - TURN_REALM=localhost
      - TURN_SECRET=${TURN_SECRET}
    networks:
      - matrix_net

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    depends_on:
      - synapse
      - element-web
    networks:
      - matrix_net

volumes:
  postgres_data:
  redis_data:
  synapse_data:

networks:
  matrix_net:
```

## .env

```bash
# Matrix/Element
POSTGRES_PASSWORD=secure_postgres_password
TURN_SECRET=secure_turn_secret

# Element at http://localhost:8080
# Synapse API at http://localhost:8008
```

## Usage notes

- Element at http://localhost:8080
- Synapse at http://localhost:8008
- Federation via port 8448
- TURN for voice/video
- Decentralized and private

## Troubleshooting

- Federation not working: Verify port 8448 is accessible externally and SSL certificate covers your domain's Matrix subdomain
- Voice/video calls failing: Check that Coturn ports 3478, 5349, and configured port range are open in firewall for UDP traffic
- Database connection errors: Ensure PostgreSQL locale settings match Synapse requirements (UTF-8, C collation) and user has proper permissions
- Element showing 'Failed to start' error: Verify config.json contains correct homeserver URL and base_url matches your domain
- High memory usage in PostgreSQL: Tune shared_buffers and effective_cache_size based on available RAM, consider vacuuming large rooms
- Synapse workers not distributing load: Check Redis connectivity and ensure worker configuration file properly defines worker types and ports

