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:
- Create a backup (optional)
- Update Synapse via pip
- Run database migrations
- Download latest Element Web
- 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.keysecure and backed up - Consider enabling rate limiting in production
- Review
/opt/synapse/homeserver.yamlfor security settings
License
MIT License