Introduction
Matrix is an open standard for interoperable, decentralized, real-time communication. This guide will help you set up your own Matrix server using Synapse (the reference implementation) and PostgreSQL.
Prerequisites :
System Requirements:
Linux server (Ubuntu 20.04/22.04 recommended)
Minimum 2GB RAM
10GB+ disk space
Root or sudo access
Software Requirements:
Docker and Docker Compose
A domain name (for production use)
Basic knowledge of Linux commands
Step 1: Install Docker and Docker Compose
# Update package lists
sudo apt update
# Install required packages
sudo apt install -y apt-transport-https ca-certificates curl software-properties-common
# Add Docker's official GPG key
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
# Add Docker repository
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
# Install Docker
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io
# Install Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/download/v2.20.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
# Add current user to docker group
sudo usermod -aG docker $USER
Step 2: Create Project Directory Structure
# Create main directory
mkdir matrix-server
cd matrix-server
# Create required directories
mkdir -p config data postgres-data
Step 3: Create Configuration Files
1. Create docker-compose.yml
version: '3.8'
services:
matrix:
image: matrixdotorg/synapse:latest
container_name: matrix
restart: unless-stopped
ports:
- "8008:8008" # Client-server API
- "8448:8448" # Federation API
volumes:
- ./config:/config
- ./data:/data
environment:
- SYNAPSE_SERVER_NAME=your-domain.com
- SYNAPSE_REPORT_STATS=no
- SYNAPSE_CONFIG_DIR=/config
- SYNAPSE_CONFIG_PATH=/config/homeserver.yaml
depends_on:
- postgres
postgres:
image: postgres:13-alpine
container_name: matrix-postgres
restart: unless-stopped
volumes:
- ./postgres-data:/var/lib/postgresql/data
environment:
- POSTGRES_PASSWORD=your_secure_password
- POSTGRES_USER=matrix
- POSTGRES_DB=matrix
- POSTGRES_INITDB_ARGS=--lc-collate=C --lc-ctype=C --encoding=UTF8
2. Generate Synapse Configuration
# Generate initial configuration
docker run -it --rm \
-v "$(pwd)/config:/config" \
-e SYNAPSE_SERVER_NAME=your-domain.com \
-e SYNAPSE_REPORT_STATS=no \
matrixdotorg/synapse:latest generate
3. Configure homeserver.yaml
Edit config/homeserver.yaml and update these key settings:
server_name: "your-domain.com"
public_baseurl: "https://your-domain.com:8448"
listeners:
- port: 8008
tls: false
type: http
x_forwarded: true
resources:
- names: [client, federation]
compress: false
database:
name: psycopg2
args:
user: matrix
password: your_secure_password
database: matrix
host: postgres
cp_min: 5
cp_max: 10
enable_registration: true # Set to false in production
Step 4: Start the Server
# Start the services
docker-compose up -d
# Check status
docker-compose ps
Step 5: Create Admin User
# Create admin user
docker-compose exec matrix register_new_matrix_user -c /config/homeserver.yaml http://localhost:8008
Step 6: Configure Reverse Proxy (Nginx)
Install Nginx:
sudo apt install nginx
Create Nginx configuration (/etc/nginx/sites-available/matrix):
server {
listen 443 ssl;
listen [::]:443 ssl;
server_name your-domain.com;
ssl_certificate /path/to/your/cert.pem;
ssl_certificate_key /path/to/your/key.pem;
location /_matrix {
proxy_pass http://localhost:8008;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Host $host;
}
location /.well-known/matrix/server {
return 200 '{"m.server": "your-domain.com:8448"}';
add_header Content-Type application/json;
}
}
Enable the site and restart Nginx:
sudo ln -s /etc/nginx/sites-available/matrix /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx
Step 7: Configure SSL/TLS
For production use, obtain SSL certificates:
# Install Certbot
sudo apt install certbot python3-certbot-nginx
# Obtain certificate
sudo certbot --nginx -d your-domain.com
Step 8: Configure Firewall
# Install UFW
sudo apt install ufw
# Configure firewall
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 8448/tcp
sudo ufw enable
Maintenance and Monitoring
Regular Updates
# Update Docker images
docker-compose pull
docker-compose up -d
Backup Strategy
# Backup database
docker-compose exec postgres pg_dump -U matrix matrix > backup.sql
# Backup configuration
tar -czf config_backup.tar.gz config/
Monitoring
Install monitoring tools:
sudo apt install htop
Troubleshooting
Server Not Starting:
docker-compose logs matrix
Database Issues:
docker-compose logs postgres
Connection Problems:
Check firewall settings
Verify DNS configuration
Test SSL certificate
Security Considerations
Regular Updates:
Keep Docker images updated
Update system packages
Monitor security advisories
Access Control:
Use strong passwords
Implement rate limiting
Configure proper firewall rules
Data Protection:
Regular backups
Encrypted storage
Secure database access
Conclusion
This setup provides a basic Matrix server configuration. For production use, consider:
Implementing additional security measures
Setting up monitoring and alerting
Configuring backup automation
Implementing rate limiting
Setting up proper logging
Remember to consult the official Synapse documentation for more detailed configuration options and best practices.