homelab-optimized/docs/services/stoatchat-next-steps.md

Stoatchat Next Steps Guide

This guide covers the remaining steps to complete your Stoatchat (Revolt Chat) setup for st.vish.gg.

🔑 1. Gmail App Password Setup

Since you're using your-email@example.com for SMTP, you need to set up a Gmail App Password:

Steps:

1. Go to Google Account Settings

   • Visit: https://myaccount.google.com/
   • Navigate to "Security"

2. Enable 2-Factor Authentication (if not already enabled)

   • Click "2-Step Verification"
   • Follow the setup process

3. Generate App Password

   • Go back to Security settings
   • Click "App passwords"
   • Select "Mail" as the app
   • Generate the password

4. Update Configuration

   cd /root/stoatchat
   nano Revolt.overrides.toml
   

   Replace GMAIL_APP_PASSWORD_REQUIRED with your actual app password: "REDACTED_PASSWORD" [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

5. Restart Services

   # Kill current services
   pkill -f revolt-
   
   # Restart them
   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 &
   

🌐 2. Cloudflare Tunnel Configuration

You need to configure your Cloudflare Tunnel to route the subdomains to the local services.

Add these entries to your tunnel configuration:

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

ingress:
  # Stoatchat API
  - hostname: api.st.vish.gg
    service: http://localhost:14702
    
  # Stoatchat WebSocket Events
  - hostname: events.st.vish.gg
    service: http://localhost:14703
    
  # Stoatchat File Server
  - hostname: files.st.vish.gg
    service: http://localhost:14704
    
  # Stoatchat Media Proxy
  - hostname: proxy.st.vish.gg
    service: http://localhost:14705
    
  # Main web app (you'll need to set this up separately)
  - hostname: st.vish.gg
    service: https://app.revolt.chat  # Or your own web client
    
  # Catch-all
  - service: http_status:404

Apply the configuration:

cloudflared tunnel route dns your-tunnel-name api.st.vish.gg
cloudflared tunnel route dns your-tunnel-name events.st.vish.gg
cloudflared tunnel route dns your-tunnel-name files.st.vish.gg
cloudflared tunnel route dns your-tunnel-name proxy.st.vish.gg
cloudflared tunnel route dns your-tunnel-name st.vish.gg

🎮 3. Web Client Setup

You have several options for the web client:

Option A: Use Official Revolt Web Client

Point st.vish.gg to https://app.revolt.chat and configure it to use your API.

Option B: Self-host the Web Client

# Clone the web client
git clone https://github.com/revoltchat/revite.git
cd revite

# Configure for your instance
echo "VITE_API_URL=https://api.st.vish.gg" > .env.local
echo "VITE_WS_URL=wss://events.st.vish.gg" >> .env.local

# Build and serve
npm install
npm run build
# Serve the dist folder via nginx or similar

🎵 4. LiveKit Voice Chat (Optional)

If you want voice/video chat functionality:

Install LiveKit Server:

# Download LiveKit
wget https://github.com/livekit/livekit/releases/latest/download/livekit_linux_amd64.tar.gz
tar -xzf livekit_linux_amd64.tar.gz
sudo mv livekit /usr/local/bin/

# Start LiveKit with your config
livekit --config livekit.yml

Configure DNS:

cloudflared tunnel route dns your-tunnel-name voice.st.vish.gg

🔍 5. Verification Steps

Test API:

curl https://api.st.vish.gg/0.8/

Test WebSocket:

# Install wscat if needed
npm install -g wscat

# Test WebSocket connection
wscat -c wss://events.st.vish.gg/

Test File Upload:

curl -X POST https://files.st.vish.gg/attachments \
  -H "Content-Type: multipart/form-data" \
  -F "file=@test.txt"

🔧 6. Service Management

Start/Stop Services:

# Start all services
cd /root/stoatchat
./scripts/start-all.sh

# Stop all services
./scripts/stop-all.sh

# Check status
ss -tlnp | grep revolt

Monitor Logs:

# View all logs
tail -f /root/stoatchat/*.log

# View specific service
tail -f /root/stoatchat/api.log

🚨 7. Troubleshooting

Common Issues:

Services not starting:

# Check dependencies
docker-compose ps

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

Email not working:

# Test SMTP connection
telnet smtp.gmail.com 587
# Should connect successfully

WebSocket connection issues:

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

# Check Cloudflare tunnel logs
cloudflared tunnel --config config.yml run

📊 8. Monitoring

Set up basic monitoring:

# Create monitoring script
cat > /root/stoatchat/monitor.sh << 'EOF'
#!/bin/bash
echo "=== Stoatchat Service Status ==="
ss -tlnp | grep revolt
echo ""
echo "=== Docker Services ==="
docker-compose ps
echo ""
echo "=== Disk Usage ==="
df -h
echo ""
echo "=== Memory Usage ==="
free -h
EOF

chmod +x /root/stoatchat/monitor.sh

# Run monitoring
./monitor.sh

✅ 9. Final Checklist

• Gmail App Password configured
• Cloudflare Tunnel routes set up
• All subdomains resolving correctly
• API responding at https://api.st.vish.gg/0.8/
• WebSocket connecting to wss://events.st.vish.gg/
• File uploads working at https://files.st.vish.gg/
• Web client accessible at https://st.vish.gg/
• Email notifications working
• Voice chat configured (optional)

Once all items are checked, your Stoatchat instance should be fully operational!

📞 Support

If you encounter issues:

1. Check the logs: tail -f /root/stoatchat/*.log
2. Verify service status: ss -tlnp | grep revolt
3. Test individual components as shown above
4. Check Stoatchat documentation: https://developers.revolt.chat/

---

This guide complements the main Stoatchat setup documentation.