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. 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. 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 Add your user to the docker group to run Docker without sudo: sudo usermod -aG docker $USER newgrp docker We’ll create a custom bridge network for Matrix services to communicate securely without exposing ports to the host: docker network create matrix-net 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 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" 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 Verify PostgreSQL is running: docker logs matrix-postgres | grep "database system is ready to accept connections" 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 Replace matrix.example.com with your registered domain name. This creates a /opt/matrix/synapse directory with the initial homeserver.yaml config file. 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 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 Also, enable federation by ensuring the public_baseurl is set to your domain: public_baseurl: https://matrix.example.com Save and close the 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 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 Stop the existing PostgreSQL container if you started it earlier: docker stop matrix-postgres && docker rm matrix-postgres Navigate to the /opt/matrix directory and start the services with Docker Compose: cd /opt/matrix docker compose up -d Verify all services are running: docker compose ps Check Synapse logs for errors: docker compose logs -f synapse 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 Create an Nginx config for your Matrix domain: sudo nano /etc/nginx/sites-available/matrix 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; } } 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 Follow the Certbot prompts to generate free SSL certificates. Test your Matrix 2.0 server with curl: curl https://matrix.example.com/_matrix/client/versions 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). By default, Synapse disables user registration. To enable it, edit /opt/matrix/synapse/homeserver.yaml: nano /opt/matrix/synapse/homeserver.yaml Set enable_registration: true (or use the register_new_user script for admin-managed registration). Restart Synapse to apply changes: docker compose restart synapse Create an admin user: docker exec -it matrix-synapse register_new_user -a -u admin -p your-admin-password 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.