echoes-of-the-ash/old/WEBSOCKET_DEPLOYMENT.md

WebSocket Deployment Guide

Quick Deployment Steps

1. Install New Dependencies

cd /opt/dockers/echoes_of_the_ashes
docker compose down
docker compose build
docker compose up -d

This will rebuild the containers with the new websockets package.

2. Verify Installation

Check that the API container started successfully:

docker compose logs api | grep "WebSocket"

You should see log entries about WebSocket connections once players connect.

3. Test WebSocket Connection

Open the game in a browser and check the console (F12):

• Look for: 🔌 Connecting to WebSocket: ws://...
• Look for: ✅ WebSocket connected

4. Monitor Active Connections

Check the health endpoint to see active WebSocket connections:

curl http://localhost:8000/health

(Can be extended to show WebSocket connection count)

5. Test Real-Time Updates

1. Movement Test:

   • Open game in two browser tabs (different accounts)
   • Move one character to a location
   • Other tab should see "Player arrived" message immediately

2. Combat Test:

   • Start combat with an NPC
   • Attacks should update immediately (no 5s delay)

3. Pickup Test:

   • Drop an item in a location
   • Other players in same location should see it disappear when picked up

Rollback (If Needed)

If WebSocket causes issues, you can roll back to pure polling:

Option 1: Disable WebSocket on Frontend

Edit pwa/src/components/Game.tsx:

const { isConnected, sendMessage } = useGameWebSocket({
  token,
  onMessage: handleWebSocketMessage,
  enabled: false  // Change true to false
})

Option 2: Remove WebSocket from Backend

Revert changes to:

• api/main.py (remove WebSocket endpoint and broadcasts)
• api/database.py (remove get_players_in_location)
• requirements.txt (remove websockets package)

Then rebuild and redeploy.

Performance Monitoring

Watch for Issues

# Monitor API logs for WebSocket errors
docker compose logs -f api | grep "WebSocket\|❌"

# Check for memory usage increases
docker stats echoes_of_the_ashes_api

# Monitor connection count (check server load)
# Add to health endpoint or check logs for "WebSocket connected/disconnected"

Expected Behavior

• Connection: Players connect within 1-2 seconds of loading game
• Reconnection: If network drops, should reconnect within 3 seconds
• Memory: ~10MB per 1,000 connections (very low)
• CPU: Should decrease compared to polling (event-driven)

Troubleshooting

WebSocket Not Connecting

1. Check CORS settings in api/main.py
2. Verify token is present: localStorage.getItem('token') in browser console
3. Check nginx/proxy configuration (if using reverse proxy)

Frequent Disconnections

1. Check heartbeat interval (30s default)
2. Verify network stability
3. Check for proxy timeouts (nginx: proxy_read_timeout 60s;)

Messages Not Received

1. Verify manager.send_personal_message() is being called
2. Check player_id matches active connection
3. Look for WebSocket send errors in logs

Next Steps After Deployment

1. Monitor for 24 hours: Check stability and error rates
2. Gather user feedback: Is latency better? Any connection issues?
3. Plan live chat: Quick win feature using WebSocket infrastructure
4. Consider party system: Next major feature enabled by WebSockets

Success Metrics

After deployment, you should see:

• ✅ 95% reduction in API request volume
• ✅ <100ms latency for game updates (vs 2500ms avg with polling)
• ✅ Lower server CPU usage (event-driven vs continuous polling)
• ✅ Improved UX - instant feedback on actions

Good luck with the deployment! 🚀