How to Install and Configure a Private

1. What We Are Setting Up and Why: The Matrix Philosophy

Matrix is not just another messenger; it is an open protocol for decentralized real-time communication. Unlike closed systems like Telegram, WhatsApp, or Slack, Matrix allows users on different servers to communicate with each other as easily as we exchange emails. This concept is called federation.

Synapse is the most mature and popular implementation of a Matrix homeserver, written in Python. It serves as a central hub that stores message history, manages accounts, and synchronizes data between clients and other servers on the network.

Why choose a self-hosted solution on a VPS instead of using public servers like matrix.org?

• Privacy: Your conversation metadata does not leave your server (unless you use federation).
• Performance: Public servers are often overloaded, leading to delays in message delivery. Your own VPS ensures instant response.
• Flexibility: You decide how much media to store, which bridges to install, and who to register on the server.

In this guide, we focus on current 2026 software versions, using containerization, which makes the installation process reproducible and clean.

2. What VPS Configuration is Needed for This Task

Matrix Synapse has historically been considered a resource-intensive service, especially regarding RAM consumption. However, with optimizations in recent years and the use of PostgreSQL, requirements have become more modest. Nevertheless, for the comfortable operation of a group of users and the use of bridges (for example, to WhatsApp or Telegram), it is not worth skimping on resources.

It is important to consider the type of disk subsystem. Matrix actively works with the database when searching and synchronizing rooms, so NVMe drives significantly increase the responsiveness of the interface in the Element client. For stable and fast messenger operation, you can rent a VPS with the specified characteristics, which will provide the necessary performance margin for the PostgreSQL database and media file caching.

When should you consider a dedicated server? If you are planning to deploy a corporate messenger for 100+ employees with terabytes of archives or if you require maximum resource isolation for security. For most private tasks and small businesses, a powerful VPS will be more than enough.

Server Location: Choose a location as close as possible to the bulk of your users. This minimizes latency when establishing WebRTC connections during calls.

3. Server Preparation: Security and Basics

Before installing Synapse, you need to prepare the operating system. We will use Ubuntu 24.04 LTS or 26.04 LTS, as they have the best support for Docker packages and fresh kernels.

First, we will update the system and create a limited user with sudo privileges so as not to work under root:

# Updating package index and system
sudo apt update && sudo apt upgrade -y

# Creating a user (replace 'adminuser' with your name)
sudo adduser adminuser
sudo usermod -aG sudo adminuser

# Switching to the new user
su - adminuser

Configuring a basic firewall (UFW) is critical. Matrix requires opening several ports:

• 80/TCP — for Let's Encrypt verification (HTTP).
• 443/TCP — main client traffic (HTTPS).
• 8448/TCP — federation (interaction between Matrix servers).
• 3478, 5349 (UDP/TCP) — for STUN/TURN operation (calls).

sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 8448/tcp
sudo ufw allow 3478/udp
sudo ufw enable

It is also recommended to install Fail2Ban to protect SSH from brute-force attacks:

sudo apt install fail2ban -y
sudo systemctl enable fail2ban
sudo systemctl start fail2ban

4. Installing Docker and Helper Utilities

By default, Synapse generates a config for SQLite, but for production on a VPS, PostgreSQL is mandatory. Let's edit /opt/matrix/synapse/data/homeserver.yaml.

Find the database section and replace it with the following:

database:
  name: psycopg2
  args:
    user: synapse
    password: your_strong_password
    database: synapse
    host: db
    cp_min: 5
    cp_max: 10

Registration Setup: By default, new user registration is closed. If you want to create the first account, temporarily enable it or use the command line. For security, it is better to leave enable_registration: false and create users manually.

Secret Keys: Ensure that registration_shared_secret is filled with a long random string. This will allow administrative tools to interact with the API.

Starting the server:

docker compose up -d

Creating the first user (administrator):

docker exec -it matrix-synapse-1 register_new_matrix_user \
    -c /data/homeserver.yaml http://localhost:8008

Follow the prompts: enter a login, password, and answer "yes" to the question about administrator rights.

7. Setting up TLS/HTTPS via Caddy and Domain Delegation

Matrix clients and other servers communicate via HTTPS. We will use Caddy because it automatically manages certificates and has an extremely simple syntax.

Add Caddy to your docker-compose.yml:

  caddy:
    image: caddy:latest
    restart: always
    ports:
      - "80:80"
      - "443:443"
      - "8448:8448"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - ./caddy_data:/data
      - ./caddy_config:/config

Create a Caddyfile in /opt/matrix:

example.com:443, example.com:8448 {
    reverse_proxy synapse:8008
    
    header {
        Access-Control-Allow-Origin *
        Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS"
        Access-Control-Allow-Headers "Origin, X-Requested-With, Content-Type, Accept, Authorization"
    }
}

Delegation (Well-known): To allow other servers to find your Matrix server, you need to configure .well-known files. This allows using the domain example.com even if Synapse itself is running on a subdomain like matrix.example.com.

Add a block to the Caddyfile to serve JSON:

example.com {
    handle_path /.well-known/matrix/server {
        header Content-Type application/json
        respond {"m.server": "example.com:443"}
    }
    handle_path /.well-known/matrix/client {
        header Content-Type application/json
        header Access-Control-Allow-Origin *
        respond {"m.homeserver": {"base_url": "https://example.com"}}
    }
}

8. Call Setup: Installing Coturn (STUN/TURN)

For audio and video calls to work via Element (especially when users are behind NAT), a TURN server is required. We will install Coturn.

Add the service to docker-compose.yml:

  coturn:
    image: coturn/coturn:latest
    restart: always
    net: host
    volumes:
      - ./coturn.conf:/etc/coturn/turnserver.conf

Example of a basic coturn.conf:

use-auth-secret
static-auth-secret=YOUR_VERY_STRONG_SECRET
realm=example.com
listening-port=3478
tls-listening-port=5349
min-port=49152
max-port=65535

In homeserver.yaml, specify the TURN server details:

turn_uris: ["turn:example.com:3478?transport=udp", "turn:example.com:3478?transport=tcp"]
turn_shared_secret: "YOUR_VERY_STRONG_SECRET"
turn_user_lifetime: 86400000

9. Backups, Updates, and Maintenance

Administering a Matrix server requires regular attention to two things: the database size and the relevance of software versions.

Backup Strategy

You need to back up three components:

1. Database: PostgreSQL dump.
2. Configuration files: homeserver.yaml, Caddyfile, signing keys.
3. Media storage: The media_store folder (the largest part).

Example of a simple backup script (backup.sh):

#!/bin/bash
BACKUP_DIR="/opt/backups/$(date +%Y-%m-%d)"
mkdir -p $BACKUP_DIR

# DB Dump
docker exec matrix-db-1 pg_dump -U synapse synapse > $BACKUP_DIR/db.sql

# Copying configs
cp /opt/matrix/synapse/data/homeserver.yaml $BACKUP_DIR/
cp /opt/matrix/synapse/data/*.signing.key $BACKUP_DIR/

# Archiving (without media to save space; it's better to back them up separately via rsync)
tar -czf $BACKUP_DIR/configs.tar.gz -C /opt/matrix/synapse/data .

Media Cache Cleanup

Matrix stores copies of all media files from federated rooms. To prevent the disk from filling up, configure automatic cleanup in homeserver.yaml:

media_retention_rules:
  - type: remote
    max_lifetime: 30d

Updating

Updating is done by changing the image tag or simply restarting with latest:

docker compose pull
docker compose up -d

10. Troubleshooting + FAQ

Error: "Federation failed" when trying to join public rooms

Check port 8448. It must be open in UFW and forwarded in Caddy. Use the Matrix Federation Tester service to ensure your certificate is valid and that SRV records or well-known files are configured correctly.

Why does Synapse consume so much RAM?

Synapse is written in Python and caches a lot of data in memory to speed up access. If memory is low, ensure you are using PostgreSQL and have configured cache limits in homeserver.yaml (the caches.global_factor parameter).

What is the minimum VPS configuration?

For a single user, 2 GB of RAM and 1 vCPU are sufficient, but the system will run slowly when joining large rooms (e.g., Matrix HQ). For stable operation, we recommend 4 GB of RAM.

What to choose — VPS or dedicated for this task?

For a personal messenger and small communities, a VPS is the ideal choice due to its flexibility and the ability to quickly back up snapshots. A dedicated server is only needed for massive volumes of media traffic or specific data security requirements.

How to connect Element X?

Element X requires support for the Sliding Sync protocol. In 2026, it is built into Synapse but may require separate activation in the configuration. Ensure your client supports Matrix protocol version 1.4+.

Can the server be moved to another domain?

Practically no. server_name is hardcoded into the IDs of all messages and rooms in the database. Changing the domain is equivalent to creating a new server from scratch.

Problem with sending notifications to mobile devices

Matrix uses a Push Gateway. For Element, the matrix.org push server is used. Ensure your server has internet access and does not block outgoing requests to port 443.

11. Conclusions and Next Steps

Congratulations! You have deployed your own full-fledged Matrix Synapse server. Now you have a secure communication platform that does not depend on the policies of third-party companies and provides full control over privacy.

As next steps, we recommend exploring:

• Installing Bridges: Connect your Telegram, WhatsApp, and Signal accounts to Matrix via mautrix bridges to use Element as a single client for all messengers.
• LDAP/OIDC Integration: If you are setting up the server for a company, connect your existing user database.
• Monitoring: Install a Prometheus + Grafana stack to track server load and Synapse resource consumption.

Matrix is a powerful tool, and owning your own node in this network makes you part of a global ecosystem of free communication.