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

   git clone https://github.com/stoatchat/stoatchat.git
   cd stoatchat
   

2. Install Dependencies

   # 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

   cp livekit.example.yml livekit.yml
   # Edit livekit.yml with your configuration
   

4. Create Production Configuration

   # 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

   docker-compose up -d
   

6. Build and Start Stoatchat Services

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

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:

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

[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

# 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

# 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

# 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

# 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

# Check dependencies
docker-compose ps

# Verify build
mise run build

# Check logs
tail -f api.log

Database connection issues

# 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

# 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

# Check events service
curl -I http://localhost:14703/

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

Performance Issues

# 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

# 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

# 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

# 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