homelab-optimized/docs/services/matrix/README.md

Matrix Synapse + Element Web Bare-Metal Installation

Production-ready Matrix homeserver with Element Web client for Ubuntu 24.04 LTS.

Features

• Synapse - Matrix homeserver with PostgreSQL backend
• Element Web - Modern web client (v1.12.8)
• Coturn - TURN server for voice/video calls
• Federation - Connect with other Matrix servers
• Nginx - Reverse proxy for HTTP traffic
• Auto-validation - YAML config validation during install

Quick Install

# On a fresh Ubuntu 24.04 VM (run as root)
export DOMAIN="mx.example.com"
export ADMIN_USER="admin"
curl -sSL https://git.vish.gg/Vish/matrix-element/raw/branch/main/install-baremetal.sh | bash

One-Liner (with defaults)

curl -sSL https://git.vish.gg/Vish/matrix-element/raw/branch/main/install-baremetal.sh | DOMAIN=mx.example.com bash

Requirements

• Ubuntu 24.04 LTS
• 2+ CPU cores
• 4GB+ RAM
• 50GB+ disk space
• Domain with DNS pointing to your server

Post-Installation

1. Configure Reverse Proxy

If using a reverse proxy (Synology, Cloudflare, etc.), point:

• https://your-domain.com:443 → http://server-ip:8080
• Enable WebSocket support

2. Port Forwarding for TURN (Voice/Video Calls)

Forward these ports to your Matrix server:

Port	Protocol	Purpose
3479	TCP/UDP	TURN
5350	TCP/UDP	TURNS (TLS)
49201-49250	UDP	Media relay

3. Change Admin Password

Login at https://your-domain.com and change the default password immediately.

Scripts

Verify Installation

# Check health of all services
./verify-matrix.sh

This checks:

• All services (synapse, nginx, coturn, postgresql)
• Matrix Client and Federation APIs
• Well-known endpoints
• Element Web accessibility
• Database status

Fix/Repair

# Diagnose and fix common issues
./fix-matrix.sh

This automatically fixes:

• YAML configuration errors in homeserver.yaml
• File ownership and permissions
• Stopped services
• Common configuration issues

Backup

# Create a full backup
./backup-matrix.sh

# Or specify custom location
BACKUP_DIR=/mnt/backup ./backup-matrix.sh

Creates:

• PostgreSQL database dump
• Configuration files
• Media files
• Signing keys
• TURN configuration

Update

# Update Synapse and Element to latest versions
./update-matrix.sh

This will:

1. Create a backup (optional)
2. Update Synapse via pip
3. Run database migrations
4. Download latest Element Web
5. Restart services

Configuration Files

File	Purpose
/opt/synapse/homeserver.yaml	Main Synapse config
/opt/synapse/*.signing.key	Server signing key (CRITICAL - backup!)
/opt/element/web/config.json	Element Web config
/etc/turnserver.conf	TURN server config
/etc/nginx/sites-available/matrix	Nginx config
/root/.matrix_secrets	Passwords and secrets

Service Management

# Check status
systemctl status synapse nginx coturn

# Restart services
systemctl restart synapse
systemctl restart nginx
systemctl restart coturn

# View logs
journalctl -u synapse -f
journalctl -u coturn -f

Federation Testing

Test federation status:

curl https://federationtester.matrix.org/api/report?server_name=your-domain.com

Adding Users

# Create a new user
cd /opt/synapse
source venv/bin/activate
register_new_matrix_user -c homeserver.yaml http://localhost:8008

# Create admin user
register_new_matrix_user -c homeserver.yaml -a http://localhost:8008

Troubleshooting

Check if services are running

systemctl status synapse nginx coturn postgresql

Test Matrix API locally

curl http://localhost:8008/_matrix/client/versions

Test well-known endpoints

curl https://your-domain.com/.well-known/matrix/server
curl https://your-domain.com/.well-known/matrix/client

Check Synapse logs

journalctl -u synapse -n 100
tail -f /opt/synapse/homeserver.log

Security Notes

• Change the admin password immediately after installation
• Keep /opt/synapse/*.signing.key secure and backed up
• Consider enabling rate limiting in production
• Review /opt/synapse/homeserver.yaml for security settings

License

MIT License