Sanitized mirror from private repository - 2026-03-30 00:10:29 UTC
This commit is contained in:
Gitea Mirror Bot
341
hosts/vms/matrix-ubuntu-vm/README.md
Normal file
341
hosts/vms/matrix-ubuntu-vm/README.md
Normal file
@@ -0,0 +1,341 @@
|
||||
# Ubuntu VM Homelab
|
||||
|
||||
Self-hosted communication platform with Mastodon, Mattermost, and Matrix/Element on a single Ubuntu VM sharing PostgreSQL.
|
||||
|
||||
## Current Deployment Status
|
||||
|
||||
| Service | Status | Domain | Internal Port | Nginx Port |
|
||||
|---------|--------|--------|---------------|------------|
|
||||
| ✅ Mastodon | Running | mastodon.vish.gg | 3000, 4000 | 8082 |
|
||||
| ✅ Mattermost | Running | mm.crista.love | 8065 | 8081 |
|
||||
| ✅ Matrix (mx.vish.gg) | Running | mx.vish.gg | 8018 | 8082 |
|
||||
| ✅ Matrix (vish - legacy) | Running | matrix.thevish.io | 8008 | 8081 |
|
||||
| ✅ PostgreSQL | Running | - | 5432 | - |
|
||||
| ✅ Redis | Running | - | 6379 | - |
|
||||
| ✅ TURN (coturn) | Running | mx.vish.gg:3479 | 3479 | - |
|
||||
|
||||
## VM Specifications
|
||||
|
||||
- **OS**: Ubuntu 24.04.4 LTS (x86_64)
|
||||
- **Hostname**: matrix-ubuntu
|
||||
- **LAN IP**: 192.168.0.154 (static) — `ssh ubuntu-matrix`
|
||||
- **Tailscale IP**: 100.85.21.51
|
||||
- **SSH user**: test
|
||||
- **RAM**: 7.7 GB
|
||||
- **CPU**: 4 cores
|
||||
- **Storage**: 96 GB
|
||||
- **Network**: Static IP set via netplan (`/etc/netplan/99-static.yaml`), cloud-init network management disabled
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Cloudflare Proxy │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Nginx │
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||||
│ │ :8080 │ │ :8081 │ │ :8082 │ │
|
||||
│ │ Matrix │ │ Mattermost │ │ Mastodon │ │
|
||||
│ └─────────────┘ └─────────────┘ └─────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
||||
│ Synapse │ │ Mattermost │ │ Mastodon │
|
||||
│ :8008 │ │ Docker │ │ Docker │
|
||||
│ + Element │ │ :8065 │ │ :3000 │
|
||||
└─────────────┘ └─────────────┘ │ :4000 │
|
||||
│ │ └─────────────┘
|
||||
│ │ │
|
||||
└───────────────────┴──────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ PostgreSQL │
|
||||
│ :5432 │
|
||||
│ │
|
||||
│ - synapse │
|
||||
│ - mattermost │
|
||||
│ - mastodon │
|
||||
└─────────────────┘
|
||||
```
|
||||
|
||||
## Databases
|
||||
|
||||
All services share the same PostgreSQL 16 server:
|
||||
|
||||
| Database | User | Purpose |
|
||||
|----------|------|---------|
|
||||
| synapse | synapse | Matrix homeserver (vish - legacy) |
|
||||
| synapse_mx | synapse_mx | Matrix homeserver (mx.vish.gg - federated) |
|
||||
| mattermost | mmuser | Mattermost |
|
||||
| mastodon_production | mastodon | Mastodon |
|
||||
|
||||
## Docker Containers
|
||||
|
||||
```
|
||||
NAMES IMAGE STATUS
|
||||
mastodon-streaming-1 ghcr.io/mastodon/mastodon-streaming:v4.5.7 Up
|
||||
mastodon-web-1 ghcr.io/mastodon/mastodon:v4.5.7 Up
|
||||
mastodon-sidekiq-1 ghcr.io/mastodon/mastodon:v4.5.7 Up
|
||||
mastodon-redis-1 redis:7-alpine Up
|
||||
mattermost mattermost/mattermost-team-edition:11.4 Up (healthy)
|
||||
```
|
||||
|
||||
## Systemd Services (bare-metal)
|
||||
|
||||
```
|
||||
UNIT SERVICE VERSION
|
||||
synapse.service Synapse (legacy) 1.148.0 — /opt/synapse, port 8008
|
||||
synapse-mx.service Synapse (primary) 1.148.0 — /opt/synapse-mx, port 8018
|
||||
```
|
||||
|
||||
Both Synapse instances share the venv at `/opt/synapse/venv/`.
|
||||
|
||||
## Quick Start
|
||||
|
||||
1. Clone this repo to your VM
|
||||
2. Copy environment templates and edit with your values
|
||||
3. Run the setup script
|
||||
|
||||
```bash
|
||||
git clone https://git.vish.gg/Vish/Ubuntu-vm-homelab.git
|
||||
cd Ubuntu-vm-homelab
|
||||
./scripts/setup.sh
|
||||
```
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
Ubuntu-vm-homelab/
|
||||
├── mastodon/
|
||||
│ ├── docker-compose.yml
|
||||
│ └── .env.production.template
|
||||
├── mattermost/
|
||||
│ ├── docker-compose.yml
|
||||
│ └── config.json.template
|
||||
├── matrix-element/
|
||||
│ ├── homeserver.yaml.template
|
||||
│ └── element-config.json.template
|
||||
├── nginx/
|
||||
│ ├── mastodon.conf
|
||||
│ ├── mattermost.conf
|
||||
│ └── matrix.conf
|
||||
├── scripts/
|
||||
│ ├── setup.sh
|
||||
│ ├── backup.sh
|
||||
│ └── update.sh
|
||||
└── README.md
|
||||
```
|
||||
|
||||
## Credentials
|
||||
|
||||
Stored securely on the server:
|
||||
- `/opt/mastodon/.env.production` - Mastodon secrets
|
||||
- `/opt/mattermost/config/config.json` - Mattermost config
|
||||
- `/opt/synapse/homeserver.yaml` - Matrix config
|
||||
|
||||
## Cloudflare Setup
|
||||
|
||||
Each service requires a DNS record pointing to the VM's public IP with Cloudflare proxy enabled.
|
||||
Configure origin rules to route to the correct nginx port.
|
||||
|
||||
## Maintenance
|
||||
|
||||
### Backup
|
||||
```bash
|
||||
./scripts/backup.sh
|
||||
```
|
||||
|
||||
### View Logs
|
||||
```bash
|
||||
# Mastodon
|
||||
cd /opt/mastodon && docker compose logs -f
|
||||
|
||||
# Mattermost
|
||||
docker logs -f mattermost
|
||||
|
||||
# Matrix (mx.vish.gg)
|
||||
tail -f /opt/synapse-mx/homeserver.log
|
||||
|
||||
# Matrix (legacy vish)
|
||||
tail -f /opt/synapse/homeserver.log
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Updating Services
|
||||
|
||||
### Update Mastodon
|
||||
|
||||
```bash
|
||||
cd /opt/mastodon
|
||||
|
||||
# Pull latest images
|
||||
docker compose pull
|
||||
|
||||
# Stop services
|
||||
docker compose down
|
||||
|
||||
# Run database migrations
|
||||
docker compose run --rm web bundle exec rails db:migrate
|
||||
|
||||
# Precompile assets (if needed)
|
||||
docker compose run --rm web bundle exec rails assets:precompile
|
||||
|
||||
# Start services
|
||||
docker compose up -d
|
||||
|
||||
# Verify
|
||||
docker compose ps
|
||||
```
|
||||
|
||||
**Check for release notes:** https://github.com/mastodon/mastodon/releases
|
||||
|
||||
### Update Mattermost
|
||||
|
||||
```bash
|
||||
cd /opt/mattermost
|
||||
|
||||
# Check current version
|
||||
docker exec mattermost mattermost version
|
||||
|
||||
# Pull latest image
|
||||
docker compose pull
|
||||
|
||||
# Stop and restart
|
||||
docker compose down
|
||||
docker compose up -d
|
||||
|
||||
# Verify
|
||||
docker logs mattermost | head -20
|
||||
```
|
||||
|
||||
**Check for release notes:** https://docs.mattermost.com/about/mattermost-server-releases.html
|
||||
|
||||
### Update Matrix Synapse (both instances share the same venv)
|
||||
|
||||
Both instances use `/opt/synapse/venv/` — upgrade once, restart both.
|
||||
|
||||
```bash
|
||||
# Check current version
|
||||
curl -s http://localhost:8018/_synapse/admin/v1/server_version
|
||||
|
||||
# Upgrade (pin to a specific version, e.g. 1.148.0)
|
||||
sudo /opt/synapse/venv/bin/pip install 'matrix-synapse==1.148.0'
|
||||
|
||||
# Restart both services
|
||||
sudo systemctl restart synapse synapse-mx
|
||||
|
||||
# Verify
|
||||
curl -s http://localhost:8008/_synapse/admin/v1/server_version # legacy
|
||||
curl -s http://localhost:8018/_synapse/admin/v1/server_version # mx
|
||||
```
|
||||
|
||||
**Check for release notes:** https://github.com/element-hq/synapse/releases
|
||||
|
||||
> **Note:** If startup fails with `InsufficientPrivilege: must be owner of table`, see
|
||||
> the DB ownership fix in `docs/MATRIX.md#db-ownership-fix`.
|
||||
|
||||
### Update Element Web
|
||||
|
||||
```bash
|
||||
# Check latest version at https://github.com/element-hq/element-web/releases
|
||||
ELEMENT_VERSION="v1.12.11" # Change to latest version
|
||||
|
||||
# Download and extract
|
||||
cd /tmp
|
||||
wget https://github.com/element-hq/element-web/releases/download/${ELEMENT_VERSION}/element-${ELEMENT_VERSION}.tar.gz
|
||||
tar -xzf element-${ELEMENT_VERSION}.tar.gz
|
||||
|
||||
# Backup current config
|
||||
cp /opt/element/web/config.json /tmp/element-config-backup.json
|
||||
|
||||
# Back up configs
|
||||
cp /opt/element/web/config.json /tmp/element-config-web.json
|
||||
cp /opt/element/web-thevish/config.json /tmp/element-config-thevish.json
|
||||
|
||||
# Replace files (both installs share the same release)
|
||||
sudo rm -rf /opt/element/web/* /opt/element/web-thevish/*
|
||||
sudo cp -r element-${ELEMENT_VERSION}/* /opt/element/web/
|
||||
sudo cp -r element-${ELEMENT_VERSION}/* /opt/element/web-thevish/
|
||||
|
||||
# Restore configs
|
||||
sudo cp /tmp/element-config-web.json /opt/element/web/config.json
|
||||
sudo cp /tmp/element-config-thevish.json /opt/element/web-thevish/config.json
|
||||
|
||||
# Verify (nginx serves static files, no restart needed)
|
||||
cat /opt/element/web/version
|
||||
cat /opt/element/web-thevish/version
|
||||
|
||||
# Cleanup
|
||||
rm -rf /tmp/element-${ELEMENT_VERSION}* /tmp/element-config-*.json
|
||||
```
|
||||
|
||||
### Update TURN Server (coturn)
|
||||
|
||||
```bash
|
||||
# Update via apt
|
||||
sudo apt update
|
||||
sudo apt upgrade coturn
|
||||
|
||||
# Restart
|
||||
sudo systemctl restart coturn
|
||||
|
||||
# Verify
|
||||
sudo systemctl status coturn
|
||||
```
|
||||
|
||||
### Update All Services (Quick Script)
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Save as /opt/scripts/update-all.sh
|
||||
|
||||
echo "=== Updating Mastodon ==="
|
||||
cd /opt/mastodon
|
||||
docker compose pull
|
||||
docker compose down
|
||||
docker compose run --rm web bundle exec rails db:migrate
|
||||
docker compose up -d
|
||||
|
||||
echo "=== Updating Mattermost ==="
|
||||
cd /opt/mattermost
|
||||
docker compose pull
|
||||
docker compose down
|
||||
docker compose up -d
|
||||
|
||||
echo "=== Updating Synapse ==="
|
||||
cd /opt/synapse
|
||||
source venv/bin/activate
|
||||
pip install --upgrade matrix-synapse
|
||||
pkill -f 'synapse.app.homeserver'
|
||||
sleep 2
|
||||
sudo -u synapse /opt/synapse/venv/bin/python -m synapse.app.homeserver \
|
||||
--config-path=/opt/synapse-mx/homeserver.yaml --daemonize
|
||||
sudo -u synapse /opt/synapse/venv/bin/python -m synapse.app.homeserver \
|
||||
--config-path=/opt/synapse/homeserver.yaml --daemonize
|
||||
|
||||
echo "=== Updating System Packages ==="
|
||||
sudo apt update && sudo apt upgrade -y
|
||||
|
||||
echo "=== Done! ==="
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Federation Status
|
||||
|
||||
| Service | Protocol | Federation |
|
||||
|---------|----------|------------|
|
||||
| Matrix (mx.vish.gg) | Matrix | ✅ Enabled |
|
||||
| Matrix (vish) | Matrix | ❌ Disabled (invalid server_name) |
|
||||
| Mastodon | ActivityPub | ✅ Enabled |
|
||||
| Mattermost | Shared Channels | ❌ Enterprise only |
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
Reference in New Issue
Block a user