Sanitized mirror from private repository - 2026-04-18 11:19:59 UTC
This commit is contained in:
Gitea Mirror Bot
259
hosts/vms/matrix-ubuntu-vm/docs/SETUP.md
Normal file
259
hosts/vms/matrix-ubuntu-vm/docs/SETUP.md
Normal file
@@ -0,0 +1,259 @@
|
||||
# Deployment Documentation
|
||||
|
||||
Complete setup guide for the Ubuntu VM Homelab with Mastodon, Mattermost, and Matrix/Element.
|
||||
|
||||
## Server Access
|
||||
|
||||
```
|
||||
IP: YOUR_WAN_IP
|
||||
SSH Port: 65533
|
||||
Username: test
|
||||
Password: "REDACTED_PASSWORD"
|
||||
```
|
||||
|
||||
## Service Credentials
|
||||
|
||||
### Mastodon Admin
|
||||
- **Username**: vish
|
||||
- **Email**: your-email@example.com
|
||||
- **Password**: `c16a0236e5a5da1e0c80bb296a290fc3`
|
||||
- **URL**: https://mastodon.vish.gg
|
||||
|
||||
### Mattermost
|
||||
- **URL**: https://mm.crista.love
|
||||
- **Admin**: (configured during first access)
|
||||
|
||||
### Matrix/Element
|
||||
- **URL**: https://mx.vish.gg
|
||||
- **Homeserver**: mx.vish.gg
|
||||
|
||||
## PostgreSQL Configuration
|
||||
|
||||
PostgreSQL 16 is configured to allow Docker container connections:
|
||||
|
||||
```
|
||||
# /etc/postgresql/16/main/pg_hba.conf
|
||||
host all all 172.17.0.0/16 md5
|
||||
host all all 0.0.0.0/0 md5
|
||||
|
||||
# /etc/postgresql/16/main/postgresql.conf
|
||||
listen_addresses = '*'
|
||||
```
|
||||
|
||||
### Database Credentials
|
||||
|
||||
| Database | User | Password |
|
||||
|----------|------|----------|
|
||||
| mastodon_production | mastodon | mastodon_pass_2026 |
|
||||
| mattermost | mmuser | (check /opt/mattermost/config/config.json) |
|
||||
| synapse | synapse | (check /opt/synapse/homeserver.yaml) |
|
||||
|
||||
## Nginx Configuration
|
||||
|
||||
### Ports
|
||||
- **8080**: Matrix/Element (mx.vish.gg)
|
||||
- **8081**: Mattermost (mm.crista.love)
|
||||
- **8082**: Mastodon (mastodon.vish.gg)
|
||||
|
||||
### Site Configs
|
||||
```
|
||||
/etc/nginx/sites-enabled/
|
||||
├── mastodon -> /etc/nginx/sites-available/mastodon
|
||||
├── matrix -> /etc/nginx/sites-available/matrix
|
||||
└── mattermost -> /etc/nginx/sites-available/mattermost
|
||||
```
|
||||
|
||||
## Mastodon Setup Details
|
||||
|
||||
### Directory Structure
|
||||
```
|
||||
/opt/mastodon/
|
||||
├── docker-compose.yml
|
||||
├── .env.production
|
||||
├── public/
|
||||
│ └── system/ # Media uploads
|
||||
└── redis/ # Redis data
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
```env
|
||||
LOCAL_DOMAIN=mastodon.vish.gg
|
||||
SINGLE_USER_MODE=false
|
||||
|
||||
# Database
|
||||
DB_HOST=172.17.0.1
|
||||
DB_PORT=5432
|
||||
DB_NAME=mastodon_production
|
||||
DB_USER=mastodon
|
||||
DB_PASS="REDACTED_PASSWORD"
|
||||
|
||||
# Redis
|
||||
REDIS_HOST=redis
|
||||
REDIS_PORT=6379
|
||||
|
||||
# SMTP (Gmail) - CONFIGURED AND WORKING ✅
|
||||
SMTP_SERVER=smtp.gmail.com
|
||||
SMTP_PORT=587
|
||||
SMTP_LOGIN=your-email@example.com
|
||||
SMTP_PASSWORD="REDACTED_PASSWORD"
|
||||
SMTP_AUTH_METHOD=plain
|
||||
SMTP_ENABLE_STARTTLS=auto
|
||||
SMTP_FROM_ADDRESS="Mastodon <notifications@mastodon.vish.gg>"
|
||||
|
||||
# Search
|
||||
ES_ENABLED=false
|
||||
```
|
||||
|
||||
### Common Commands
|
||||
```bash
|
||||
# View logs
|
||||
cd /opt/mastodon && docker compose logs -f
|
||||
|
||||
# Restart services
|
||||
cd /opt/mastodon && docker compose restart
|
||||
|
||||
# Run admin commands
|
||||
cd /opt/mastodon && docker compose exec web bin/tootctl <command>
|
||||
|
||||
# Create new user
|
||||
docker compose run --rm web bin/tootctl accounts create USERNAME --email=EMAIL --confirmed --role=Owner
|
||||
|
||||
# Database migration
|
||||
docker compose run --rm web bundle exec rake db:migrate
|
||||
```
|
||||
|
||||
## Mattermost Setup Details
|
||||
|
||||
### Directory Structure
|
||||
```
|
||||
/opt/mattermost/
|
||||
├── config/
|
||||
│ └── config.json
|
||||
├── data/
|
||||
├── logs/
|
||||
├── plugins/
|
||||
└── client/plugins/
|
||||
```
|
||||
|
||||
### Docker Command
|
||||
```bash
|
||||
docker run -d --name mattermost \
|
||||
-p 8065:8065 \
|
||||
-v /opt/mattermost/config:/mattermost/config \
|
||||
-v /opt/mattermost/data:/mattermost/data \
|
||||
-v /opt/mattermost/logs:/mattermost/logs \
|
||||
-v /opt/mattermost/plugins:/mattermost/plugins \
|
||||
--restart=always \
|
||||
mattermost/mattermost-team-edition:11.3
|
||||
```
|
||||
|
||||
## Matrix/Synapse Setup Details
|
||||
|
||||
### Directory Structure
|
||||
```
|
||||
/opt/synapse/
|
||||
├── homeserver.yaml
|
||||
├── *.signing.key
|
||||
└── media_store/
|
||||
|
||||
/opt/element/web/
|
||||
└── (Element Web static files)
|
||||
```
|
||||
|
||||
### Synapse Service
|
||||
```bash
|
||||
# Status
|
||||
systemctl status matrix-synapse
|
||||
|
||||
# Restart
|
||||
systemctl restart matrix-synapse
|
||||
|
||||
# Logs
|
||||
journalctl -u matrix-synapse -f
|
||||
```
|
||||
|
||||
## Cloudflare Configuration
|
||||
|
||||
For each service, configure Cloudflare:
|
||||
|
||||
1. **DNS Records** (A records pointing to VM public IP)
|
||||
- mastodon.vish.gg
|
||||
- mm.crista.love
|
||||
- mx.vish.gg
|
||||
|
||||
2. **Origin Rules** (Route to correct nginx port)
|
||||
- mastodon.vish.gg → Port 8082
|
||||
- mm.crista.love → Port 8081
|
||||
- mx.vish.gg → Port 8080
|
||||
|
||||
3. **SSL/TLS**: Full (strict)
|
||||
|
||||
## Federation (Mastodon)
|
||||
|
||||
Federation requires:
|
||||
1. ✅ Proper LOCAL_DOMAIN in .env.production
|
||||
2. ✅ HTTPS via Cloudflare
|
||||
3. ✅ Webfinger endpoint responding at `/.well-known/webfinger`
|
||||
4. ⏳ DNS properly configured
|
||||
|
||||
Test federation:
|
||||
```bash
|
||||
# From another server
|
||||
curl "https://mastodon.vish.gg/.well-known/webfinger?resource=acct:vish@mastodon.vish.gg"
|
||||
```
|
||||
|
||||
## SMTP Configuration (Gmail)
|
||||
|
||||
To send emails via Gmail:
|
||||
|
||||
1. Enable 2-Factor Authentication on your Google account
|
||||
2. Generate an App Password:
|
||||
- Go to https://myaccount.google.com/apppasswords
|
||||
- Create a new app password for "Mail"
|
||||
3. Update `/opt/mastodon/.env.production`:
|
||||
```
|
||||
SMTP_PASSWORD="REDACTED_PASSWORD"
|
||||
```
|
||||
4. Restart Mastodon:
|
||||
```bash
|
||||
cd /opt/mastodon && docker compose restart
|
||||
```
|
||||
|
||||
## Backup Locations
|
||||
|
||||
```
|
||||
/backup/
|
||||
├── YYYYMMDD_HHMMSS/
|
||||
│ ├── mattermost.sql
|
||||
│ ├── synapse.sql
|
||||
│ ├── mastodon.sql
|
||||
│ ├── mastodon_media.tar.gz
|
||||
│ ├── mattermost_data.tar.gz
|
||||
│ └── synapse_data.tar.gz
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Mastodon 403 Forbidden
|
||||
- Normal when accessing with wrong Host header
|
||||
- Always access via proper domain or use `-H "Host: mastodon.vish.gg"`
|
||||
|
||||
### Federation Not Working
|
||||
- Check Cloudflare proxy is enabled
|
||||
- Verify DNS resolves correctly
|
||||
- Test webfinger endpoint externally
|
||||
|
||||
### Database Connection Errors
|
||||
- Verify PostgreSQL is listening on all interfaces
|
||||
- Check pg_hba.conf allows Docker network
|
||||
- Restart PostgreSQL: `systemctl restart postgresql`
|
||||
|
||||
### Container Won't Start
|
||||
```bash
|
||||
# Check logs
|
||||
docker logs <container_name>
|
||||
|
||||
# Check Docker network
|
||||
docker network ls
|
||||
docker network inspect mastodon_internal_network
|
||||
```
|
||||
Reference in New Issue
Block a user