homelab-optimized/docs/services/stoatchat-setup.md

# Stoatchat (Revolt Chat Backend) Setup Guide

**🟢 Chat Service**

## 📋 Service Overview

| Property | Value |
|----------|-------|
| **Service Name** | stoatchat (Revolt Chat Backend) |
| **Host** | homelab_vm |
| **Category** | Communication |
| **Difficulty** | 🔴 Advanced |
| **Domain** | st.vish.gg |
| **Repository** | https://github.com/stoatchat/stoatchat |
| **Technology** | Rust, MongoDB, Redis, MinIO |

## 🎯 Purpose

Stoatchat is a self-hosted Revolt chat backend that provides a Discord-like chat experience with full control over your data. It includes API, WebSocket events, file handling, media proxy, and voice chat capabilities.

## 🏗️ Architecture

### Core Services
- **API Server** (revolt-delta): Main REST API endpoint
- **Events Server** (revolt-bonfire): WebSocket events and real-time communication
- **Files Server** (revolt-autumn): File uploads, downloads, and storage
- **Proxy Server** (revolt-january): Media proxy and external content handling
- **Gifbox Server** (revolt-gifbox): GIF processing and optimization

### Background Services
- **Push Daemon** (revolt-pushd): Push notifications
- **Cron Daemon** (revolt-crond): Scheduled tasks and maintenance

### Supporting Infrastructure
- **MongoDB**: Primary database
- **Redis/KeyDB**: Caching and session management
- **MinIO**: S3-compatible object storage for files
- **RabbitMQ**: Message queuing
- **MailDev**: Email testing (development)
- **LiveKit**: Voice and video chat (optional)

## 🚀 Quick Start

### Prerequisites
- Ubuntu/Debian Linux system
- Docker and Docker Compose
- Rust toolchain (managed via mise)
- Domain with Cloudflare DNS (st.vish.gg)
- At least 4GB RAM and 20GB storage

### Installation Steps

1. **Clone the Repository**
   ```bash
   git clone https://github.com/stoatchat/stoatchat.git
   cd stoatchat
   ```

2. **Install Dependencies**
   ```bash
   # Install mise (Rust toolchain manager)
   curl https://mise.run | sh
   echo 'eval "$(~/.local/bin/mise activate bash)"' >> ~/.bashrc
   source ~/.bashrc
   
   # Install system dependencies
   sudo apt update
   sudo apt install -y pkg-config libssl-dev build-essential
   ```

3. **Configure LiveKit**
   ```bash
   cp livekit.example.yml livekit.yml
   # Edit livekit.yml with your configuration
   ```

4. **Create Production Configuration**
   ```bash
   # Create Revolt.overrides.toml with domain settings
   cat > Revolt.overrides.toml << 'EOF'
   [api]
   url = "https://api.st.vish.gg"

   [events]
   url = "wss://events.st.vish.gg"

   [autumn]
   url = "https://files.st.vish.gg"

   [january]
   url = "https://proxy.st.vish.gg"

   [livekit]
   url = "wss://voice.st.vish.gg"

   [email]
   smtp_host = "protonmail-bridge"
   smtp_port = 25
   smtp_username = ""
   smtp_password = ""
   from_address = "noreply@st.vish.gg"
   EOF
   ```

5. **Start Supporting Services**
   ```bash
   docker-compose up -d
   ```

6. **Build and Start Stoatchat Services**
   ```bash
   # Build the project
   mise run build
   
   # Start all services
   mise service:api > api.log 2>&1 &
   mise service:events > events.log 2>&1 &
   mise service:files > files.log 2>&1 &
   mise service:proxy > proxy.log 2>&1 &
   mise service:gifbox > gifbox.log 2>&1 &
   mise service:pushd > pushd.log 2>&1 &
   mise service:crond > crond.log 2>&1 &
   ```

## 🔧 Configuration

### Domain Configuration (st.vish.gg)

The following subdomains need to be configured in Cloudflare:

| Subdomain | Purpose | Local Port | SSL Required |
|-----------|---------|------------|--------------|
| `st.vish.gg` | Main web app | - | Yes |
| `api.st.vish.gg` | REST API | 14702 | Yes |
| `events.st.vish.gg` | WebSocket events | 14703 | Yes |
| `files.st.vish.gg` | File uploads/downloads | 14704 | Yes |
| `proxy.st.vish.gg` | Media proxy | 14705 | Yes |
| `voice.st.vish.gg` | Voice chat (LiveKit) | - | Yes |

### Cloudflare Tunnel Configuration

Add these entries to your Cloudflare Tunnel configuration:

```yaml
tunnel: your-tunnel-id
credentials-file: /path/to/credentials.json

ingress:
  - hostname: api.st.vish.gg
    service: http://localhost:14702
  - hostname: events.st.vish.gg
    service: http://localhost:14703
  - hostname: files.st.vish.gg
    service: http://localhost:14704
  - hostname: proxy.st.vish.gg
    service: http://localhost:14705
  - hostname: st.vish.gg
    service: https://app.revolt.chat
  - service: http_status:404
```

### Email Configuration

Stoatchat uses Gmail SMTP for email notifications:

```toml
[email]
smtp_host = "smtp.gmail.com"
smtp_port = 587
smtp_username = "your-email@example.com"
smtp_password = "REDACTED_PASSWORD"
from_address = "your-email@example.com"
smtp_tls = true
```

**Note**: You'll need to generate a Gmail App Password:
1. Go to Google Account settings
2. Enable 2-Factor Authentication
3. Generate an App Password for "Mail"
4. Use this App Password in the configuration

### Environment Variables

Key environment variables in `Revolt.overrides.toml`:

```toml
[database]
mongodb = "mongodb://localhost:27017/revolt"

[redis]
url = "redis://localhost:6380"

[s3]
endpoint = "http://localhost:14009"
access_key_id = "minioadmin"
secret_access_key = "minioadmin"
bucket = "revolt-files"
region = "us-east-1"

[rabbitmq]
url = "amqp://guest:guest@localhost:5672"
```

## 🌐 Service Ports

### Stoatchat Services
| Service | Port | Purpose |
|---------|------|---------|
| revolt-delta (API) | 14702 | REST API endpoints |
| revolt-bonfire (Events) | 14703 | WebSocket connections |
| revolt-autumn (Files) | 14704 | File upload/download |
| revolt-january (Proxy) | 14705 | Media proxy |
| revolt-gifbox | 14706 | GIF processing |

### Supporting Services
| Service | Port | Purpose |
|---------|------|---------|
| MongoDB | 27017 | Database |
| Redis/KeyDB | 6380 | Cache |
| MinIO API | 14009 | Object storage API |
| MinIO Console | 14010 | Storage management |
| RabbitMQ | 5672 | Message queue |
| RabbitMQ Management | 15672 | Queue management |
| MailDev Web | 14080 | Email testing |
| MailDev SMTP | 14025 | Email relay |

## 🔒 Security Considerations

### Firewall Configuration
```bash
# Allow only necessary ports
sudo ufw allow 22/tcp    # SSH
sudo ufw allow 80/tcp    # HTTP (redirect)
sudo ufw allow 443/tcp   # HTTPS
sudo ufw enable
```

### SSL/TLS
- All external traffic must use HTTPS/WSS
- Cloudflare provides SSL termination
- Internal services communicate over HTTP (behind proxy)

### Authentication
- Configure user registration settings in `Revolt.overrides.toml`
- Set up admin accounts after deployment
- Consider enabling invite-only mode for private instances

## 📊 Resource Requirements

### Minimum Requirements
- **CPU**: 4 cores
- **RAM**: 4GB
- **Storage**: 20GB SSD
- **Network**: 100Mbps

### Recommended Production
- **CPU**: 8 cores
- **RAM**: 8GB+
- **Storage**: 100GB+ SSD
- **Network**: 1Gbps

### Resource Monitoring
```bash
# Monitor all services
docker stats
htop

# Check service logs
tail -f api.log events.log files.log

# Monitor disk usage
df -h
du -sh /var/lib/docker/
```

## 🔍 Health Monitoring

### Service Status Checks
```bash
# Check if services are running
ss -tlnp | grep revolt

# Test API endpoint
curl -s http://localhost:14702/0.8/ | jq

# Test file service
curl -s http://localhost:14704/ | jq

# Check WebSocket (requires wscat)
wscat -c ws://localhost:14703/
```

### Log Monitoring
```bash
# View real-time logs
tail -f *.log

# Check for errors
grep -i error *.log

# Monitor resource usage
docker stats --no-stream
```

## 🚨 Troubleshooting

### Common Issues

**Services won't start**
```bash
# Check dependencies
docker-compose ps

# Verify build
mise run build

# Check logs
tail -f api.log
```

**Database connection issues**
```bash
# Test MongoDB connection
docker exec -it stoatchat-database-1 mongosh

# Check Redis connection
docker exec -it stoatchat-redis-1 redis-cli ping
```

**File upload problems**
```bash
# Check MinIO status
curl http://localhost:14009/minio/health/live

# Verify bucket exists
docker exec -it stoatchat-minio-1 mc ls local/
```

**WebSocket connection failures**
```bash
# Check events service
curl -I http://localhost:14703/

# Verify proxy configuration
curl -H "Upgrade: websocket" http://localhost:14703/
```

### Performance Issues
```bash
# Monitor resource usage
htop
iotop
nethogs

# Check database performance
docker exec -it stoatchat-database-1 mongosh --eval "db.stats()"

# Analyze slow queries
docker logs stoatchat-database-1 | grep slow
```

## 🔄 Maintenance

### Regular Tasks
```bash
# Update services
git pull
mise run build
# Restart services

# Clean up logs
find . -name "*.log" -size +100M -delete

# Database maintenance
docker exec -it stoatchat-database-1 mongosh --eval "db.runCommand({compact: 'messages'})"
```

### Backup Procedures
```bash
# Backup database
docker exec stoatchat-database-1 mongodump --out /backup/$(date +%Y%m%d)

# Backup files
rsync -av /var/lib/docker/volumes/stoatchat_minio_data/ /backup/files/

# Backup configuration
cp Revolt.overrides.toml /backup/config/
```

### Updates
```bash
# Update stoatchat
git pull origin main
mise run build

# Restart services (zero-downtime)
# Stop services one by one and restart
pkill -f revolt-delta
mise service:api > api.log 2>&1 &
# Repeat for other services
```

## 📚 Additional Resources

- **Official Documentation**: https://developers.revolt.chat/
- **GitHub Repository**: https://github.com/stoatchat/stoatchat
- **Community Discord**: https://revolt.chat/invite/01F7ZSBSFHQ8TA81725KQCSDDP
- **API Documentation**: https://developers.revolt.chat/api/
- **Self-hosting Guide**: https://developers.revolt.chat/self-hosting/

## 🔗 Related Services

- **Gmail SMTP**: Email integration
- **Cloudflare Tunnel**: External access
- **Nginx Proxy Manager**: Alternative reverse proxy
- **Authentik**: SSO integration (future)

---

*This documentation covers the complete setup and maintenance of Stoatchat for the st.vish.gg domain.*

**Last Updated**: $(date +%Y-%m-%d)  
**Configuration**: Production setup with ProtonMail integration