homelab-optimized/docs/services/matrix/SETUP.md

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

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

# 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

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

# 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:

# 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:

   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

# Check logs
docker logs <container_name>

# Check Docker network
docker network ls
docker network inspect mastodon_internal_network