惯性聚合 高效追踪和阅读你感兴趣的博客、新闻、科技资讯
阅读原文 在惯性聚合中打开

推荐订阅源

Blog — PlanetScale
Blog — PlanetScale
Y
Y Combinator Blog
G
Google Developers Blog
Cyber Security Advisories - MS-ISAC
Cyber Security Advisories - MS-ISAC
L
LangChain Blog
S
SegmentFault 最新的问题
J
Java Code Geeks
V
Visual Studio Blog
H
Help Net Security
Stack Overflow Blog
Stack Overflow Blog
aimingoo的专栏
aimingoo的专栏
OSCHINA 社区最新新闻
OSCHINA 社区最新新闻
T
Tailwind CSS Blog
Microsoft Azure Blog
Microsoft Azure Blog
博客园_首页
H
Hackread – Cybersecurity News, Data Breaches, AI and More
奇客Solidot–传递最新科技情报
奇客Solidot–传递最新科技情报
博客园 - Franky
B
Blog RSS Feed
The Cloudflare Blog
MyScale Blog
MyScale Blog
月光博客
月光博客
Microsoft Security Blog
Microsoft Security Blog
美团技术团队

DEV Community

Authentication Security Deep Dive: From Brute Force to Salted Hashing (With Java Examples) Why AI Systems Don’t Fail — They Drift Spilling beans for how i learn for exam😁"Reinforcement Learning Cheat Sheet" I Replaced Chrome with Safari for AI Browser Automation. Here's What Broke (and What Finally Worked) How Python Borrows Other People's Work The $40 Architecture: Processing 1 Billion API Requests with 99.99% Uptime Vibe Coding: A Workflow Guide (From Zero to SaaS) Most webhook security guides protect the wrong side. The scary part is delivery. Headless CMS for TanStack Start: Build a Blog with Cosmic EU Age Verification App "Hacked in 2 Minutes" — What Actually Happened Comfy Cloud’s delete function does not actually remove files Running AI Models on GPU Cloud Servers: A Beginner Guide Event-driven media intelligence with AWS Step Functions and Bedrock I scored 500 AI prompts across 8 quality dimensions — here's what broke How to Call Google Gemini API from Next.js (Free Tier, No Backend Needed) The Portal Protocol: Reclaiming Human Connection in the Age of AI How to Fix Your Team's Scattered Knowledge Problem With a Self-Hosted Forum Intro to tc Cloud Functors: A Graph-First Mental Model for the Modern Cloud Designing Multi-Tenant Backends With Both Ownership and Team Access I Built a Neumorphic CSS Library with 77+ Components — Here's What I Learned PostgreSQL Performance Optimization: Why Connection Pooling Is Critical at Scale Cómo construí un SaaS multi-rubro para gestionar expensas en Argentina con FastAPI + Vue 3 🚀 I Built an Ethical Hacking Scanner Tool – Open Source Project I Replaced /usage and /context in Claude Code With a Single Statusline A Pythonic Way to Handle Emails (IMAP/SMTP) with Auto-Discovery and AI-Ready Design I Collected 8.9 Million Polymarket Price Points — Here's What I Found About How Markets Really Move EcoTrack AI — Carbon Footprint Tracker & Dashboard Everyone's Using AI. No One Agrees How. 5 self-hosted ebook managers worth trying in 2026 Building Your First AI Agent with LangChain: From Chatbot to Autonomous Assistant
Step-by-Step: Self-Host Matrix 2.0 with Docker 27 and Pos...
ANKUSH CHOUD · 2026-05-02 · via DEV Community

ANKUSH CHOUDHARY JOHAL

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.