claudePySnake/web/README.md

Web Client Deployment

This directory contains the web client for the Multiplayer Snake game.

Development Mode

For local development, use the built-in HTTP server:

python run_server.py --name "Dev Server"

This starts:

• TCP server on port 8888 (for pygame clients)
• WebSocket server on port 8889 (for web clients)
• HTTP server on port 8000 (serving web files)

Access the web client at: http://localhost:8000

Production Deployment with nginx

For production, disable the built-in HTTP server and use nginx to serve static files and proxy WebSocket connections.

Step 1: Run server without HTTP

python run_server.py --no-http --host 0.0.0.0

Step 2: Configure nginx

Create an nginx configuration file (e.g., /etc/nginx/sites-available/snake-game):

server {
    listen 80;
    server_name snake.example.com;

    # Serve static web files
    location / {
        root /path/to/multiplayer-snake/web;
        try_files $uri $uri/ /index.html;

        # Cache static assets
        location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
            expires 1y;
            add_header Cache-Control "public, immutable";
        }
    }

    # Proxy WebSocket connections
    location /ws {
        proxy_pass http://localhost:8889;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSocket timeouts
        proxy_read_timeout 86400;
        proxy_send_timeout 86400;
    }
}

Enable the site:

sudo ln -s /etc/nginx/sites-available/snake-game /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Step 3: Update web client URL

Users should connect to: ws://snake.example.com/ws (or wss:// for SSL)

SSL/TLS Support (HTTPS + WSS)

For secure connections with Let's Encrypt:

server {
    listen 80;
    server_name snake.example.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name snake.example.com;

    ssl_certificate /etc/letsencrypt/live/snake.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/snake.example.com/privkey.pem;

    # SSL configuration
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers on;
    ssl_ciphers 'ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384';

    # Static files
    location / {
        root /path/to/multiplayer-snake/web;
        try_files $uri $uri/ /index.html;
    }

    # Secure WebSocket
    location /ws {
        proxy_pass http://localhost:8889;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_read_timeout 86400;
        proxy_send_timeout 86400;
    }
}

Apache Configuration

For Apache with mod_proxy_wstunnel:

<VirtualHost *:80>
    ServerName snake.example.com
    DocumentRoot /path/to/multiplayer-snake/web

    <Directory /path/to/multiplayer-snake/web>
        Options -Indexes +FollowSymLinks
        AllowOverride None
        Require all granted
    </Directory>

    # WebSocket proxy
    ProxyPass /ws ws://localhost:8889
    ProxyPassReverse /ws ws://localhost:8889

    # Enable WebSocket
    RewriteEngine On
    RewriteCond %{HTTP:Upgrade} websocket [NC]
    RewriteCond %{HTTP:Connection} upgrade [NC]
    RewriteRule /ws/(.*) ws://localhost:8889/$1 [P,L]
</VirtualHost>

Enable required modules:

sudo a2enmod proxy proxy_http proxy_wstunnel rewrite
sudo systemctl restart apache2

Caddy Configuration

Caddy makes it even simpler with automatic HTTPS:

snake.example.com {
    root * /path/to/multiplayer-snake/web
    file_server

    handle /ws {
        reverse_proxy localhost:8889
    }
}

Systemd Service

Create /etc/systemd/system/snake-game.service:

[Unit]
Description=Snake Game Server
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/path/to/multiplayer-snake
ExecStart=/path/to/multiplayer-snake/venv/bin/python run_server.py --no-http --host 0.0.0.0
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable snake-game
sudo systemctl start snake-game
sudo systemctl status snake-game

Firewall Configuration

Open required ports:

# HTTP/HTTPS (nginx/Apache)
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

# Game server TCP (if accessed directly)
sudo ufw allow 8888/tcp

# WebSocket (if not behind proxy)
sudo ufw allow 8889/tcp

Troubleshooting

WebSocket connection fails

• Check firewall rules
• Verify nginx/Apache WebSocket proxy configuration
• Check browser console for errors
• Test WebSocket endpoint: wscat -c ws://your-server:8889

Static files not loading

• Verify nginx root path is correct
• Check file permissions: chmod -R 755 /path/to/web
• Check nginx error logs: sudo tail -f /var/log/nginx/error.log

Game server not starting

• Check if ports are already in use: sudo netstat -tulpn | grep 8889
• Review server logs
• Verify Python dependencies are installed