DEV Community

ANKUSH CHOUDHARY JOHAL
ANKUSH CHOUDHARY JOHAL

Posted on • Originally published at johal.in

Step-by-Step: Self-Host Matrix 2.0 with Docker 27 and PostgreSQL 17

#stepbystep #selfhost #matrix #docker

Step-by-Step: Self-Host Matrix 2.0 with Docker 27 and PostgreSQL 17

Matrix 2.0 is the latest iteration of the open, decentralized communication protocol, bringing improved performance, native VoIP, and better room management to self-hosted and federated deployments. Self-hosting Matrix gives you full control over your data, avoids vendor lock-in, and lets you customize your communication stack. This guide walks you through deploying Matrix 2.0 (using the Synapse reference server) with Docker 27 and PostgreSQL 17, two industry-standard tools for containerization and relational data storage.

Prerequisites

Before starting, ensure you have:

  • A Linux server (Ubuntu 22.04 LTS or newer is recommended) with at least 2GB RAM, 2 CPU cores, and 20GB free storage.
  • Docker 27 installed (we’ll cover installation below if needed).
  • A registered domain name (e.g., matrix.example.com) pointed to your server’s public IP via A/AAAA records.
  • Ports 80 (HTTP), 443 (HTTPS), and 8448 (Matrix federation) open in your firewall.
  • Root or sudo access to the server.

Step 1: Install Docker 27 and Docker Compose

Docker 27 includes native support for Docker Compose v2, so we only need to install the Docker engine. Run the following commands to install Docker 27 via the official repository:

# Remove old Docker versions
sudo apt-get remove docker docker-engine docker.io containerd runc

# Install prerequisites
sudo apt-get update
sudo apt-get install ca-certificates curl gnupg

# Add Docker official GPG key
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Add Docker repository
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker 27
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Verify Docker 27 installation
docker --version
# Output should include Docker version 27.x.x
Enter fullscreen mode Exit fullscreen mode

Add your user to the docker group to run Docker without sudo:

sudo usermod -aG docker $USER
newgrp docker
Enter fullscreen mode Exit fullscreen mode

Step 2: Create a Dedicated Docker Network

We’ll create a custom bridge network for Matrix services to communicate securely without exposing ports to the host:

docker network create matrix-net
Enter fullscreen mode Exit fullscreen mode

Step 3: Deploy PostgreSQL 17

We’ll run the official PostgreSQL 17 container for Matrix’s persistent data storage. First, create a directory to store PostgreSQL data:

mkdir -p /opt/matrix/postgres
cd /opt/matrix
Enter fullscreen mode Exit fullscreen mode

Set a secure password for the PostgreSQL user (replace your-secure-password with a strong password):

export POSTGRES_PASSWORD="your-secure-password"
export POSTGRES_USER="matrix"
export POSTGRES_DB="synapse"
Enter fullscreen mode Exit fullscreen mode

Run the PostgreSQL 17 container:

docker run -d \
  --name matrix-postgres \
  --network matrix-net \
  -v /opt/matrix/postgres:/var/lib/postgresql/data \
  -e POSTGRES_PASSWORD=$POSTGRES_PASSWORD \
  -e POSTGRES_USER=$POSTGRES_USER \
  -e POSTGRES_DB=$POSTGRES_DB \
  --restart unless-stopped \
  postgres:17
Enter fullscreen mode Exit fullscreen mode

Verify PostgreSQL is running:

docker logs matrix-postgres | grep "database system is ready to accept connections"
Enter fullscreen mode Exit fullscreen mode

Step 4: Generate Matrix Synapse Configuration

Synapse is the reference Matrix 2.0 server. We’ll generate its initial configuration using a temporary Synapse container:

docker run -it --rm \
  --network matrix-net \
  -v /opt/matrix/synapse:/data \
  matrixdotorg/synapse:latest \
  generate-config --server-name matrix.example.com --report-stats no
Enter fullscreen mode Exit fullscreen mode

Replace matrix.example.com with your registered domain name. This creates a /opt/matrix/synapse directory with the initial homeserver.yaml config file.

Step 5: Configure Synapse to Use PostgreSQL 17

Edit the generated /opt/matrix/synapse/homeserver.yaml to replace the default SQLite database with PostgreSQL 17. Open the file with a text editor:

nano /opt/matrix/synapse/homeserver.yaml
Enter fullscreen mode Exit fullscreen mode

Find the database section and replace it with the following (update the password to match your PostgreSQL password):

database:
  name: psycopg2
  args:
    user: matrix
    password: your-secure-password
    database: synapse
    host: matrix-postgres
    port: 5432
    cp_min: 5
    cp_max: 10
Enter fullscreen mode Exit fullscreen mode

Also, enable federation by ensuring the public_baseurl is set to your domain:

public_baseurl: https://matrix.example.com
Enter fullscreen mode Exit fullscreen mode

Save and close the file.

Step 6: Create Docker Compose File

We’ll use Docker Compose to manage the Synapse and PostgreSQL services (though we already started PostgreSQL, we’ll consolidate into a compose file for easier management). Create /opt/matrix/docker-compose.yml:

nano /opt/matrix/docker-compose.yml
Enter fullscreen mode Exit fullscreen mode

Paste the following content (update domain names and passwords as needed):

version: '3.8'

services:
  postgres:
    image: postgres:17
    container_name: matrix-postgres
    restart: unless-stopped
    environment:
      POSTGRES_USER: matrix
      POSTGRES_PASSWORD: your-secure-password
      POSTGRES_DB: synapse
    volumes:
      - /opt/matrix/postgres:/var/lib/postgresql/data
    networks:
      - matrix-net
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U matrix"]
      interval: 10s
      timeout: 5s
      retries: 5

  synapse:
    image: matrixdotorg/synapse:latest
    container_name: matrix-synapse
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
    volumes:
      - /opt/matrix/synapse:/data
    environment:
      - SYNAPSE_SERVER_NAME=matrix.example.com
      - SYNAPSE_REPORT_STATS=no
    ports:
      - "8448:8008"
    networks:
      - matrix-net

networks:
  matrix-net:
    external: true
Enter fullscreen mode Exit fullscreen mode

Stop the existing PostgreSQL container if you started it earlier:

docker stop matrix-postgres && docker rm matrix-postgres
Enter fullscreen mode Exit fullscreen mode

Step 7: Deploy the Stack

Navigate to the /opt/matrix directory and start the services with Docker Compose:

cd /opt/matrix
docker compose up -d
Enter fullscreen mode Exit fullscreen mode

Verify all services are running:

docker compose ps
Enter fullscreen mode Exit fullscreen mode

Check Synapse logs for errors:

docker compose logs -f synapse
Enter fullscreen mode Exit fullscreen mode

Step 8: Set Up Reverse Proxy and SSL

Matrix requires valid SSL certificates for federation and client access. We’ll use Nginx and Let’s Encrypt for this. Install Nginx:

sudo apt-get install nginx certbot python3-certbot-nginx
Enter fullscreen mode Exit fullscreen mode

Create an Nginx config for your Matrix domain:

sudo nano /etc/nginx/sites-available/matrix
Enter fullscreen mode Exit fullscreen mode

Paste the following (replace matrix.example.com with your domain):

server {
    listen 80;
    listen [::]:80;
    server_name matrix.example.com;

    location /.well-known/matrix/server {
        return 200 '{"m.server": "matrix.example.com:8448"}';
        default_type application/json;
    }

    location /.well-known/matrix/client {
        return 200 '{"m.homeserver": {"base_url": "https://matrix.example.com"}}';
        default_type application/json;
        add_header Access-Control-Allow-Origin *;
    }

    location / {
        proxy_pass http://localhost:8448;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Host $host;
    }
}
Enter fullscreen mode Exit fullscreen mode

Enable the config and get SSL certificates:

sudo ln -s /etc/nginx/sites-available/matrix /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
sudo certbot --nginx -d matrix.example.com
Enter fullscreen mode Exit fullscreen mode

Follow the Certbot prompts to generate free SSL certificates.

Step 9: Verify the Deployment

Test your Matrix 2.0 server with curl:

curl https://matrix.example.com/_matrix/client/versions
Enter fullscreen mode Exit fullscreen mode

You should receive a JSON response listing supported Matrix versions, including 2.0. To test with a client, download Element (https://element.io) and sign in with your domain (@user:matrix.example.com).

Step 10: Post-Install Configuration

By default, Synapse disables user registration. To enable it, edit /opt/matrix/synapse/homeserver.yaml:

nano /opt/matrix/synapse/homeserver.yaml
Enter fullscreen mode Exit fullscreen mode

Set enable_registration: true (or use the register_new_user script for admin-managed registration). Restart Synapse to apply changes:

docker compose restart synapse
Enter fullscreen mode Exit fullscreen mode

Create an admin user:

docker exec -it matrix-synapse register_new_user -a -u admin -p your-admin-password
Enter fullscreen mode Exit fullscreen mode

Conclusion

You’ve now successfully self-hosted Matrix 2.0 using Docker 27 and PostgreSQL 17. Your deployment is federated, secure, and ready for use. Next steps include configuring room directories, enabling VoIP, and setting up bridges to other communication platforms like Slack or Discord.

Top comments (0)