Ask me anything
Ithy Logo
Sign in to save

Docker Compose for Synapse with PostgreSQL Backend

Docker Compose for Synapse with PostgreSQL Backend

This document provides a comprehensive docker-compose.yml configuration for deploying Synapse, a Matrix homeserver, with a PostgreSQL database backend. It includes detailed explanations, configuration examples, and additional considerations for a robust setup. This setup also includes an optional Nginx reverse proxy for handling TLS/SSL and routing.

docker-compose.yml Configuration

Below is the docker-compose.yml file that defines the services for Synapse, PostgreSQL, and an optional Nginx reverse proxy:

    
version: '3.8'

services:
  synapse:
    image: matrixdotorg/synapse:latest
    container_name: synapse
    restart: always
    environment:
      - SYNAPSE_SERVER_NAME=your.matrix.domain
      - SYNAPSE_REPORT_STATS=no
      - POSTGRES_HOST=db
      - POSTGRES_PORT=5432
      - POSTGRES_USER=synapse
      - POSTGRES_PASSWORD=your_postgres_password
      - POSTGRES_DB=synapse
    volumes:
      - ./synapse-data:/data
    depends_on:
      - db
    ports:
      - "8008:8008"

  db:
    image: postgres:14.1-alpine
    container_name: postgres
    restart: always
    environment:
      - POSTGRES_USER=synapse
      - POSTGRES_PASSWORD=your_postgres_password
      - POSTGRES_DB=synapse
    volumes:
      - db_data:/var/lib/postgresql/data
    ports:
      - "5432:5432" # Optional: Expose for direct access (use with caution)

  nginx:
    image: nginx:latest
    container_name: nginx
    restart: always
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./certs:/etc/nginx/certs:ro
    ports:
      - "80:80"
      - "443:443"
    depends_on:
      - synapse

volumes:
  db_data:
    driver: local

Explanation of Services

1. Synapse Service

  • Image: Uses the official Synapse Docker image (matrixdotorg/synapse:latest). This ensures you are using the most up-to-date version of Synapse.
  • Container Name: The container is named synapse for easy reference.
  • Restart Policy: The restart: always policy ensures that the Synapse container restarts automatically if it crashes or the Docker daemon restarts.
  • Environment Variables:
    • SYNAPSE_SERVER_NAME: Set this to your domain name (e.g., matrix.example.com). This is crucial for federation and client connections.
    • SYNAPSE_REPORT_STATS: Set to yes or no depending on whether you want to report anonymous usage statistics. It's generally recommended to set this to no for privacy reasons.
    • POSTGRES_HOST: Specifies the hostname of the PostgreSQL database service, which is db in this case. Docker Compose uses the service name as the hostname for inter-container communication.
    • POSTGRES_PORT: Specifies the port number for the PostgreSQL database, which is 5432.
    • POSTGRES_USER: The username for accessing the PostgreSQL database, set to synapse.
    • POSTGRES_PASSWORD: The password for the PostgreSQL user. Important: Replace your_postgres_password with a strong, unique password. Consider using Docker secrets for managing sensitive information in production environments.
    • POSTGRES_DB: The name of the PostgreSQL database, set to synapse.
  • Volumes:
    • ./synapse-data:/data: Maps a local directory named synapse-data to the /data directory inside the container. This directory will store Synapse's configuration files, media files, and database files. This ensures data persistence across container restarts.
  • Dependencies:
    • depends_on: - db: Ensures that the Synapse container starts only after the PostgreSQL container is up and running.
  • Ports:
    • "8008:8008": Exposes port 8008 on the host machine, which is the default port for Synapse's HTTP API. This port is used for client-server communication.

2. PostgreSQL Service

  • Image: Uses the official lightweight PostgreSQL image (postgres:14.1-alpine). The alpine variant is smaller and more efficient.
  • Container Name: The container is named postgres for easy reference.
  • Restart Policy: The restart: always policy ensures that the PostgreSQL container restarts automatically if it crashes or the Docker daemon restarts.
  • Environment Variables:
    • POSTGRES_USER: The username for accessing the PostgreSQL database, set to synapse.
    • POSTGRES_PASSWORD: The password for the PostgreSQL user. Important: Replace your_postgres_password with a strong, unique password. This should match the password used in the Synapse service configuration.
    • POSTGRES_DB: The name of the PostgreSQL database, set to synapse.
  • Volumes:
    • db_data:/var/lib/postgresql/data: Creates a named volume db_data and maps it to the /var/lib/postgresql/data directory inside the container. This ensures that the PostgreSQL data is persisted across container restarts.
  • Ports:
    • "5432:5432": Exposes port 5432 on the host machine. Note: This is optional and generally not recommended for production environments. It's primarily useful for direct database access for maintenance or debugging. If you expose this port, ensure you have proper firewall rules in place.

3. Nginx Service (Optional)

  • Image: Uses the official Nginx image (nginx:latest).
  • Container Name: The container is named nginx for easy reference.
  • Restart Policy: The restart: always policy ensures that the Nginx container restarts automatically if it crashes or the Docker daemon restarts.
  • Volumes:
    • ./nginx.conf:/etc/nginx/nginx.conf:ro: Mounts a custom Nginx configuration file from the host machine to the /etc/nginx/nginx.conf path inside the container. The :ro flag makes the mount read-only.
    • ./certs:/etc/nginx/certs:ro: Mounts a directory containing SSL certificates from the host machine to the /etc/nginx/certs path inside the container. The :ro flag makes the mount read-only.
  • Ports:
    • "80:80": Exposes port 80 on the host machine for HTTP traffic. This is typically used to redirect HTTP traffic to HTTPS.
    • "443:443": Exposes port 443 on the host machine for HTTPS traffic.
  • Dependencies:
    • depends_on: - synapse: Ensures that the Nginx container starts only after the Synapse container is up and running.

4. Volumes

  • db_data: This named volume is used to persist the PostgreSQL database data. Docker manages the storage of this volume.

Custom Nginx Configuration (nginx.conf)

The following is an example of a basic nginx.conf file. You will need to adjust this to your specific needs, especially the server_name and the paths to your SSL certificates.

    
http {
    server {
        listen 80;
        server_name your.matrix.domain;

        # Redirect HTTP to HTTPS
        return 301 https://$host$request_uri;
    }

    server {
        listen 443 ssl;
        server_name your.matrix.domain;

        ssl_certificate /etc/nginx/certs/fullchain.pem;
        ssl_certificate_key /etc/nginx/certs/privkey.pem;

        location / {
            proxy_pass http://synapse:8008;
            proxy_set_header Host $host;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
        }
    }
}
  • Replace your.matrix.domain with your actual domain name.
  • Place your SSL certificates (fullchain.pem and privkey.pem) in the ./certs directory. You can obtain these from a trusted Certificate Authority (CA) or generate self-signed certificates for testing purposes.

Steps to Set Up

  1. Prepare Directories: Create the following directories in the same location as your docker-compose.yml file:

    • synapse-data: For Synapse data.
    • certs: For SSL certificates.

  2. Create Nginx Configuration: Create an nginx.conf file with the content provided above and save it in the same directory as your docker-compose.yml file.

  3. Generate Synapse Configuration: Run the following command to generate the initial Synapse configuration:

            
docker run -it --rm \
  -v $(pwd)/synapse-data:/data \
  -e SYNAPSE_SERVER_NAME=your.matrix.domain \
  -e SYNAPSE_REPORT_STATS=no \
  matrixdotorg/synapse:latest generate

    Replace your.matrix.domain with your actual domain name. This command will create a homeserver.yaml file in the synapse-data directory.

  4. Configure Synapse for PostgreSQL:

    • Open the homeserver.yaml file in the synapse-data directory.
    • Comment out the SQLite configuration block.
    • Uncomment and configure the PostgreSQL block as follows: 
                  
database:
  name: psycopg2
  args:
    user: synapse
    password: your_postgres_password
    database: synapse
    host: db
    port: 5432
      Important: Ensure that the password matches the POSTGRES_PASSWORD environment variable you set in the docker-compose.yml file.

  5. Start the Services: Run the following command to start all services:

            
docker-compose up -d

  6. Verify the Setup:

    • Access Synapse's client-server API at http://your.matrix.domain:8008 (if not using Nginx).
    • If using Nginx, access it via https://your.matrix.domain.

Additional Considerations

  • Environment Variables: For sensitive information like passwords, consider using a .env file or Docker secrets to manage them securely. A .env file can be created in the same directory as your docker-compose.yml file and referenced in the docker-compose.yml file using ${VARIABLE_NAME} syntax.

  • HTTPS Certificates: Ensure you have valid SSL certificates for your domain. You can use Let's Encrypt to obtain free certificates. Place the fullchain.pem and privkey.pem files in the ./certs directory.

  • Database Backup: Implement a backup strategy for your PostgreSQL database to prevent data loss. You can use tools like pg_dump or Docker volume backups.

  • Monitoring: Set up monitoring for your Synapse and PostgreSQL services to track performance and identify potential issues.

  • Scaling: For larger deployments, consider scaling Synapse horizontally by adding more worker processes. You can also use a load balancer to distribute traffic across multiple Synapse instances.

  • Firewall: Ensure that your server's firewall is configured correctly to allow traffic on the necessary ports (80, 443, and optionally 5432 if you expose it).

Relevant Documentation

github.com
Synapse Docker README
hub.docker.com
PostgreSQL Docker Hub
doc.traefik.io
Traefik Documentation

This comprehensive guide should provide you with a solid foundation for deploying Synapse with a PostgreSQL backend using Docker Compose. Remember to adjust the configuration to your specific requirements and always prioritize security best practices.


December 15, 2024

AI-assisted research. Sources, methodology and corrections · Source-checked guides and tools · Explore published answers

Ask Ithy AI