Sanitized mirror from private repository - 2026-03-15 11:02:17 UTC
This commit is contained in:
Gitea Mirror Bot
197
deployments/matrix/README.md
Normal file
197
deployments/matrix/README.md
Normal file
@@ -0,0 +1,197 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user