9.9 KiB
9.9 KiB
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
-
Clone the Repository
git clone https://github.com/stoatchat/stoatchat.git cd stoatchat -
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 -
Configure LiveKit
cp livekit.example.yml livekit.yml # Edit livekit.yml with your configuration -
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 -
Start Supporting Services
docker-compose up -d -
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:
- Go to Google Account settings
- Enable 2-Factor Authentication
- Generate an App Password for "Mail"
- 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