# 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