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

Stoatchat Migration Guide

This guide covers migrating the Stoatchat deployment from the Seattle VM to a new server.

Pre-Migration Checklist

1. Document Current State

# On Seattle VM - document current configuration
cd /root/stoatchat

# Save current configuration
cp Revolt.overrides.toml Revolt.overrides.toml.backup
cp livekit.yml livekit.yml.backup
cp compose.yml compose.yml.backup

# Document running services
ps aux | grep revolt > running_services.txt
ss -tlnp | grep -E "(14702|14703|14704|14705|14706|7880)" > port_status.txt

# Check Docker services
docker-compose ps > docker_status.txt

2. Backup Data

# Create backup directory
mkdir -p /root/stoatchat-backup/$(date +%Y%m%d)
cd /root/stoatchat-backup/$(date +%Y%m%d)

# Backup MongoDB
docker exec stoatchat-mongodb mongodump --uri="mongodb://stoatchat:stoatchat_secure_password_change_me@localhost:27017/revolt" --out ./mongodb-backup

# Backup MinIO data
docker exec stoatchat-minio tar czf - /data > minio-backup.tar.gz

# Backup Redis data (optional - mostly cache)
docker exec stoatchat-redis redis-cli BGSAVE
docker cp stoatchat-redis:/data/dump.rdb ./redis-backup.rdb

# Backup configuration files
cp /root/stoatchat/Revolt.overrides.toml ./
cp /root/stoatchat/livekit.yml ./
cp /root/stoatchat/compose.yml ./
cp -r /etc/nginx/sites-available/stoatchat ./nginx-config

# Backup SSL certificates
sudo tar czf letsencrypt-backup.tar.gz /etc/letsencrypt/

3. Test Backup Integrity

# Verify MongoDB backup
ls -la mongodb-backup/revolt/
mongorestore --dry-run --uri="mongodb://stoatchat:stoatchat_secure_password_change_me@localhost:27017/revolt-test" mongodb-backup/

# Verify MinIO backup
tar -tzf minio-backup.tar.gz | head -10

# Verify configuration files
cat Revolt.overrides.toml | grep -E "(mongodb|redis|s3_)"

Migration Process

Phase 1: Prepare New Server

1.1 Server Setup

# On new server - follow deployment guide steps 1-2
# Install dependencies, Docker, Rust
# Clone repository and build services

1.2 DNS Preparation

# Update Cloudflare DNS to point to new server IP
# Or use Cloudflare API with your token (see Vaultwarden → Homelab → Cloudflare)

# Example API call to update DNS:
curl -X PUT "https://api.cloudflare.com/client/v4/zones/ZONE_ID/dns_records/RECORD_ID" \
  -H "Authorization: Bearer <CLOUDFLARE_TOKEN>" \
  -H "Content-Type: application/json" \
  --data '{"type":"A","name":"api.st.vish.gg","content":"NEW_SERVER_IP"}'

Phase 2: Data Migration

2.1 Transfer Backup Files

# From Seattle VM to new server
scp -r /root/stoatchat-backup/$(date +%Y%m%d)/* root@NEW_SERVER_IP:/root/stoatchat-restore/

# Or use rsync for better reliability
rsync -avz --progress /root/stoatchat-backup/$(date +%Y%m%d)/ root@NEW_SERVER_IP:/root/stoatchat-restore/

2.2 Restore Configuration

# On new server
cd /root/stoatchat-restore

# Restore configuration files
cp Revolt.overrides.toml /root/stoatchat/
cp livekit.yml /root/stoatchat/
cp compose.yml /root/stoatchat/

# Update configuration for new server if needed
sed -i 's/OLD_SERVER_IP/NEW_SERVER_IP/g' /root/stoatchat/Revolt.overrides.toml

2.3 Restore SSL Certificates

# On new server
cd /root/stoatchat-restore

# Restore Let's Encrypt certificates
sudo tar xzf letsencrypt-backup.tar.gz -C /

# Or obtain new certificates
certbot certonly --nginx -d st.vish.gg -d api.st.vish.gg -d events.st.vish.gg -d files.st.vish.gg -d proxy.st.vish.gg -d voice.st.vish.gg

2.4 Setup Infrastructure Services

# On new server
cd /root/stoatchat

# Start infrastructure services
docker-compose up -d

# Wait for services to be ready
sleep 30

2.5 Restore Data

# Restore MongoDB
docker exec -i stoatchat-mongodb mongorestore --uri="mongodb://stoatchat:stoatchat_secure_password_change_me@localhost:27017" --drop /root/stoatchat-restore/mongodb-backup/

# Restore MinIO data
docker exec -i stoatchat-minio sh -c 'cd / && tar xzf -' < /root/stoatchat-restore/minio-backup.tar.gz

# Restart MinIO to recognize new data
docker-compose restart minio

Phase 3: Service Migration

3.1 Configure Nginx

# On new server
cp /root/stoatchat-restore/nginx-config /etc/nginx/sites-available/stoatchat
ln -s /etc/nginx/sites-available/stoatchat /etc/nginx/sites-enabled/

# Test and reload nginx
nginx -t
systemctl reload nginx

3.2 Start Stoatchat Services

# On new server
cd /root/stoatchat

# Start services
nohup ./target/debug/revolt-delta > api.log 2>&1 &
nohup ./target/debug/revolt-bonfire > events.log 2>&1 &
nohup ./target/debug/revolt-autumn > files.log 2>&1 &
nohup ./target/debug/revolt-january > proxy.log 2>&1 &
nohup ./target/debug/revolt-gifbox > gifbox.log 2>&1 &

Phase 4: Verification and Testing

4.1 Service Health Check

# Check all services are running
ps aux | grep revolt
ss -tlnp | grep -E "(14702|14703|14704|14705|14706|7880)"

# Test endpoints
curl -k https://api.st.vish.gg/
curl -k https://files.st.vish.gg/
curl -k https://proxy.st.vish.gg/
curl -k https://voice.st.vish.gg/

4.2 Data Integrity Check

# Check MongoDB data
docker exec stoatchat-mongodb mongo --eval "db.adminCommand('listCollections')" revolt

# Check MinIO data
docker exec stoatchat-minio mc ls local/revolt-uploads/

# Check Redis connectivity
docker exec stoatchat-redis redis-cli ping

4.3 Functional Testing

# Test API endpoints
curl -X GET https://api.st.vish.gg/users/@me -H "Authorization: Bearer TEST_TOKEN"

# Test file upload (if you have test files)
curl -X POST https://files.st.vish.gg/attachments -F "file=@test.jpg"

# Test WebSocket connection (using wscat if available)
wscat -c wss://events.st.vish.gg/

Post-Migration Tasks

1. Update DNS (if not done earlier)

# Update all DNS records to point to new server
# api.st.vish.gg -> NEW_SERVER_IP
# events.st.vish.gg -> NEW_SERVER_IP
# files.st.vish.gg -> NEW_SERVER_IP
# proxy.st.vish.gg -> NEW_SERVER_IP
# voice.st.vish.gg -> NEW_SERVER_IP
# st.vish.gg -> NEW_SERVER_IP

2. Update Monitoring

# Update any monitoring systems to check new server
# Update health check URLs
# Update alerting configurations

3. Cleanup Old Server

# On Seattle VM - ONLY after confirming new server works
# Stop services
pkill -f revolt-

# Stop Docker services
docker-compose down

# Archive data (don't delete immediately)
mv /root/stoatchat /root/stoatchat-archived-$(date +%Y%m%d)

Rollback Plan

If migration fails, you can quickly rollback:

1. Immediate Rollback

# Update DNS back to Seattle VM IP
# Restart services on Seattle VM

# On Seattle VM
cd /root/stoatchat
docker-compose up -d
./start-services.sh

2. Data Rollback

# If data was corrupted during migration
# Restore from backup on Seattle VM

cd /root/stoatchat-backup/$(date +%Y%m%d)
# Follow restore procedures above

Migration Checklist

Pre-Migration

• Document current state
• Create complete backup
• Test backup integrity
• Prepare new server
• Plan DNS update strategy

During Migration

• Transfer backup files
• Restore configuration
• Setup infrastructure services
• Restore data
• Configure nginx
• Start Stoatchat services

Post-Migration

• Verify all services running
• Test all endpoints
• Check data integrity
• Update DNS records
• Update monitoring
• Archive old server data

Rollback Ready

• Keep old server running until confirmed
• Have DNS rollback plan
• Keep backup accessible
• Document any issues found

Troubleshooting Common Issues

Services Won't Start

# Check logs
tail -f /root/stoatchat/*.log

# Check configuration
cat /root/stoatchat/Revolt.overrides.toml | grep -E "(mongodb|redis)"

# Check infrastructure services
docker-compose logs

Database Connection Issues

# Test MongoDB connection
docker exec stoatchat-mongodb mongo --eval "db.adminCommand('ismaster')"

# Check credentials
grep mongodb /root/stoatchat/Revolt.overrides.toml

SSL Certificate Issues

# Check certificate validity
openssl x509 -in /etc/letsencrypt/live/api.st.vish.gg/fullchain.pem -text -noout

# Renew certificates if needed
certbot renew --dry-run

DNS Propagation Issues

# Check DNS resolution
dig api.st.vish.gg
nslookup api.st.vish.gg 8.8.8.8

# Check from different locations
curl -H "Host: api.st.vish.gg" http://NEW_SERVER_IP/

---

This migration guide provides a comprehensive process for moving Stoatchat to a new server while minimizing downtime and ensuring data integrity.