# Matrix Synapse Server

> Self-hosted Matrix homeserver with Synapse, Element web client, and PostgreSQL.

- Category: Productivity & Collaboration
- Difficulty: advanced
- Components: synapse, element-web, postgresql, nginx
- Tags: matrix, synapse, chat, element, federation
- Source: https://selfhostrecipes.com/productivity/matrix-synapse-stack

## Overview

Matrix Synapse is the reference homeserver implementation of the Matrix protocol, an open-source real-time communication system designed for decentralized messaging, voice, and video. Developed by the Matrix.org Foundation, Synapse enables organizations and individuals to host their own communication server while maintaining the ability to federate with other Matrix homeservers across the internet, creating a distributed network similar to email but for modern chat applications.

This stack combines Synapse with Element Web (the flagship Matrix web client), PostgreSQL for robust data persistence, and NGINX for reverse proxy and SSL termination. PostgreSQL provides ACID-compliant storage for chat history, user accounts, and room state data, while NGINX handles client connections, federation traffic on port 8448, and serves the Element web interface. The configuration supports full Matrix federation, allowing users to communicate with anyone on the Matrix network while maintaining complete control over their data.

This deployment suits organizations seeking data sovereignty in their communications, privacy-conscious teams wanting end-to-end encrypted chat, or homelab enthusiasts building self-hosted alternatives to Slack or Discord. The combination provides enterprise-grade messaging capabilities with the flexibility to customize features, implement custom authentication systems, or integrate with existing infrastructure while maintaining compatibility with the broader Matrix ecosystem.

## Features

- Full Matrix protocol federation enabling communication with users on any Matrix homeserver worldwide
- End-to-end encryption support with cross-device verification for secure communications
- PostgreSQL backend with optimized schema for chat message storage and room state management
- Element Web client integration providing modern chat interface with file sharing and voice/video calls
- NGINX reverse proxy handling both client traffic and Matrix federation on dedicated port 8448
- Room management with granular permissions, moderation tools, and custom power levels
- Bridge support for connecting to IRC, Discord, Telegram, and other chat platforms
- Application service integration allowing custom bots and Matrix protocol extensions

## Use cases

- Corporate communication server replacing proprietary solutions like Slack or Microsoft Teams
- Privacy-focused community chat for open source projects or activist organizations
- Educational institution messaging platform with room-based class organization
- Gaming community server with voice chat integration and custom bot development
- Healthcare or legal organizations requiring HIPAA/GDPR compliant messaging with data residency
- Homelab enthusiasts building personal communication infrastructure for family or friend groups
- Development teams needing integrated chat with custom webhooks and CI/CD notifications

## Prerequisites

- Minimum 2GB RAM recommended for Synapse with PostgreSQL (1GB+ for PostgreSQL, 1GB+ for Synapse)
- Valid domain name with DNS control for Matrix federation and SSL certificate setup
- Ports 80, 443, and 8448 accessible from internet for web client and Matrix federation
- SSL/TLS certificates configured in nginx.conf for HTTPS and federation security
- Understanding of Matrix concepts like homeserver names, user IDs, and federation requirements
- Basic NGINX configuration knowledge for customizing reverse proxy settings

## docker-compose.yml

```yaml
services:
  synapse:
    image: matrixdotorg/synapse:latest
    environment:
      SYNAPSE_SERVER_NAME: ${MATRIX_SERVER_NAME}
      SYNAPSE_REPORT_STATS: "no"
    volumes:
      - synapse_data:/data
    depends_on:
      postgres:
        condition: service_healthy
    networks:
      - matrix-net
    restart: unless-stopped

  postgres:
    image: postgres:15-alpine
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      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
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER}"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - matrix-net
    restart: unless-stopped

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

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

volumes:
  synapse_data:
  postgres_data:

networks:
  matrix-net:
    driver: bridge
```

## .env

```bash
# Matrix Server Name
MATRIX_SERVER_NAME=matrix.example.com

# PostgreSQL
POSTGRES_USER=synapse
POSTGRES_PASSWORD=secure_postgres_password
```

## Usage notes

- Generate config: docker run --rm -v ./synapse_data:/data matrixdotorg/synapse:latest generate
- Element web at https://chat.example.com
- Federation port 8448 must be accessible
- Register users: docker exec synapse register_new_matrix_user

## Troubleshooting

- Federation not working with 'Host not found' errors: Ensure port 8448 is open and DNS SRV records are configured correctly for your domain
- Synapse container failing with database connection errors: Check PostgreSQL health check passes and POSTGRES_PASSWORD environment variable matches Synapse configuration
- Element web showing 'Failed to connect to homeserver': Verify nginx.conf properly proxies /_matrix/ endpoints to Synapse container and SSL certificates are valid
- High memory usage from PostgreSQL: Tune shared_buffers and work_mem in postgresql.conf, consider enabling connection pooling in Synapse configuration
- Registration failing with 'User already exists': Use register_new_matrix_user command with --admin flag for admin users, or enable open registration in homeserver.yaml
- Slow message delivery in large rooms: Enable worker mode in Synapse configuration and consider implementing Redis for better performance scaling

