How to Run a Local Matrix Server for Secure Communications

npub16d8gxt2z4k9e8sdpc0yyqzf5gp0np09ls4lnn630qzxzvwpl0rgq5h4rzv

How to Run a Local Matrix Server for Secure Communications

Running a self-hosted Matrix server allows you to take control of your communications, ensuring privacy and sovereignty. By hosting your own homeserver, you eliminate reliance on centralized services while maintaining encrypted, federated messaging. This guide covers the full installation process for setting up a Matrix homeserver using Synapse, the official reference implementation.

1. Prerequisites

Hardware & System Requirements

• A dedicated or virtual server running Ubuntu 22.04 LTS (or Debian-based OS)
• Minimum 2GB RAM (4GB+ recommended for production)
• At least 10GB disk space (more if storing media)
• A public domain name (optional for federation)

Dependencies

Ensure your system is updated and install required packages:

sudo apt update && sudo apt upgrade -y
    sudo apt install -y curl wget gnupg2 lsb-release software-properties-common python3-pip virtualenv
    

2. Install Matrix Synapse

Step 1: Add Matrix Repository

sudo apt install -y lsb-release wget apt-transport-https
    sudo wget -O /usr/share/keyrings/matrix-keyring.asc https://packages.matrix.org/debian/matrix-org-archive-keyring.gpg
    echo "deb [signed-by=/usr/share/keyrings/matrix-keyring.asc] https://packages.matrix.org/debian/ $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/matrix-org.list
    sudo apt update
    

Step 2: Install Synapse

sudo apt install -y matrix-synapse-py3
    

During installation, enter your desired domain name (e.g., matrix.example.com).

Step 3: Start and Enable Synapse

sudo systemctl enable --now matrix-synapse
    

3. Configure Matrix Homeserver

Step 1: Edit the Configuration File

sudo nano /etc/matrix-synapse/homeserver.yaml
    

• Set server_name to your domain (example.com)
• Enable registration if needed (enable_registration: true)
• Configure log level (log_level: INFO)

Save and exit (CTRL+X, then Y).

Step 2: Restart Synapse

sudo systemctl restart matrix-synapse
    

4. Set Up a Reverse Proxy (NGINX + Let’s Encrypt SSL)

Step 1: Install NGINX and Certbot

sudo apt install -y nginx certbot python3-certbot-nginx
    

Step 2: Obtain SSL Certificate

sudo certbot --nginx -d matrix.example.com
    

Step 3: Configure NGINX

Create a new file:

sudo nano /etc/nginx/sites-available/matrix
    

Paste the following configuration:

server {
        listen 80;
        server_name matrix.example.com;
        return 301 https://$host$request_uri;
    }
    
    server {
        listen 443 ssl;
        server_name matrix.example.com;
    
        ssl_certificate /etc/letsencrypt/live/matrix.example.com/fullchain.pem;
        ssl_certificate_key /etc/letsencrypt/live/matrix.example.com/privkey.pem;
    
        location /_matrix/ {
            proxy_pass http://localhost:8008;
            proxy_set_header X-Forwarded-For $remote_addr;
            proxy_set_header Host $host;
            proxy_set_header X-Forwarded-Proto $scheme;
        }
    }
    

Save and exit.

Step 4: Enable the Configuration

sudo ln -s /etc/nginx/sites-available/matrix /etc/nginx/sites-enabled/
    sudo systemctl restart nginx
    

5. Create an Admin User

Run the following command:

register_new_matrix_user -c /etc/matrix-synapse/homeserver.yaml http://localhost:8008
    

Follow the prompts to create an admin user.

6. Test Your Matrix Server

• Open a browser and go to: https://matrix.example.com/_matrix/client/versions
• You should see a JSON response indicating your homeserver is running.
• Use Element (https://element.io) to log in with your new user credentials.

7. Federation (Optional)

To allow federation, ensure your DNS has an SRV record:

_matrix._tcp.example.com. 3600 IN SRV 10 5 443 matrix.example.com.
    

You can check your federation status at:
https://federationtester.matrix.org/

8. Additional Features

Bridges (Connect to Other Platforms)

• Discord Bridge: https://github.com/Half-Shot/matrix-appservice-discord
• Telegram Bridge: https://github.com/tulir/mautrix-telegram

Hosting a TURN Server (For Calls & Video)

Install coturn for improved call reliability:

sudo apt install -y coturn
    

Edit /etc/turnserver.conf to include:

listening-port=3478
    fingerprint
    use-auth-secret
    static-auth-secret=your-random-secret
    realm=matrix.example.com
    

Enable and start the service:

sudo systemctl enable --now coturn
    

9. Backup & Maintenance

Database Backup

sudo systemctl stop matrix-synapse
    sudo tar -czvf matrix-backup.tar.gz /var/lib/matrix-synapse/
    sudo systemctl start matrix-synapse
    

Updating Synapse

sudo apt update && sudo apt upgrade -y matrix-synapse-py3
    sudo systemctl restart matrix-synapse
    

Connections

• Self-Hosting for Digital Sovereignty
• Nostr and Matrix Integration for Decentralized Messaging

Donations via

• lightninglayerhash@getalby.com