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
```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
```