198 lines
4.2 KiB
Markdown
198 lines
4.2 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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)
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
curl https://federationtester.matrix.org/api/report?server_name=your-domain.com
|
|
```
|
|
|
|
## Adding Users
|
|
|
|
```bash
|
|
# 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
|
|
```bash
|
|
systemctl status synapse nginx coturn postgresql
|
|
```
|
|
|
|
### Test Matrix API locally
|
|
```bash
|
|
curl http://localhost:8008/_matrix/client/versions
|
|
```
|
|
|
|
### Test well-known endpoints
|
|
```bash
|
|
curl https://your-domain.com/.well-known/matrix/server
|
|
curl https://your-domain.com/.well-known/matrix/client
|
|
```
|
|
|
|
### Check Synapse logs
|
|
```bash
|
|
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
|