Scribble.rs Deployment and Usage Guide

1. Prerequisites

Required Software

• Go 1.25.0 or later - The application is written in Go
• Git - For cloning the repository (or download ZIP as alternative)
• Docker (optional but recommended) - For containerized deployment

Optional Dependencies

• nginx or another reverse proxy - For production deployments with WebSocket support
• Prometheus - For monitoring metrics (endpoint available at /v1/metrics)

2. Installation

Option A: Using Docker (Recommended)

Docker images are available for both Linux and Windows:

Linux/Mac/WSL:

docker pull biosmarcel/scribble.rs:latest

Windows (native Windows containers only):

docker pull biosmarcel/scribble.rs:windows-latest

Option B: From Source

git clone https://github.com/scribble-rs/scribble.rs.git
cd scribble.rs
go build ./cmd/scribblers

Option C: Pre-compiled Binaries

Download from the Releases page. Note that compatibility with your system is not guaranteed.

3. Configuration

Configuration is read from environment variables or a .env file in the working directory.

Essential Configuration

Game Settings Bounds

These define limits for lobby creation (from lobby.go):

Lobby Cleanup Settings

Example .env file:

PORT=8080
ROOT_PATH=/scribble
CORS_ALLOWED_ORIGINS=https://yourdomain.com
MIN_DRAWING_TIME=60
MAX_DRAWING_TIME=180

4. Build & Run

Development Build

# Clone and build
git clone https://github.com/scribble-rs/scribble.rs.git
cd scribble.rs
go build ./cmd/scribblers

# Run with custom port
PORT=3000 ./scribblers

Production Build

# Build optimized binary
go build -ldflags="-s -w" ./cmd/scribblers

# Run with environment variables
export PORT=8080
export ROOT_PATH=/pictionary
./scribblers

Docker Run

# Basic run (maps host port 80 to container port 8080)
docker run --pull always --env PORT=8080 -p 80:8080 biosmarcel/scribble.rs:latest

# With custom configuration
docker run --pull always \
  --env PORT=8080 \
  --env ROOT_PATH=/draw \
  --env CORS_ALLOWED_ORIGINS=https://example.com \
  -p 8080:8080 \
  biosmarcel/scribble.rs:latest

5. Deployment

Docker Deployment

Create a docker-compose.yml for easy management:

version: '3.8'
services:
  scribblers:
    image: biosmarcel/scribble.rs:latest
    container_name: scribblers
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      - PORT=8080
      - ROOT_PATH=/game
      - LOBBY_CLEANUP_INTERVAL=90s
      - LOBBY_CLEANUP_PLAYER_INACTIVITY_THRESHOLD=75s

Reverse Proxy Setup (nginx)

Since Scribble.rs uses WebSockets, configure nginx:

location / {
    proxy_pass http://localhost:8080;
    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;
}

Deployment Platforms

• Fly.io - Used by the official instance (supports automatic scaling)
• AWS ECS/EKS - For containerized deployments
• DigitalOcean App Platform - Simple container deployment
• Heroku - With Docker support
• Self-hosted - Any Linux server with Docker

Systemd Service (Linux)

Create /etc/systemd/system/scribblers.service:

[Unit]
Description=Scribble.rs Pictionary Game
After=network.target

[Service]
Type=simple
User=scribble
WorkingDirectory=/opt/scribblers
EnvironmentFile=/etc/scribblers/.env
ExecStart=/opt/scribblers/scribblers
Restart=always

[Install]
WantedBy=multi-user.target

6. Troubleshooting

Common Issues

1. WebSocket connections fail behind reverse proxy

• Solution: Ensure your reverse proxy is configured to handle WebSocket upgrades (see nginx configuration above).

2. "Connection refused" errors

• Solution: Check if the server is binding to the correct address. Use NETWORK_ADDRESS=0.0.0.0 to bind to all interfaces.

3. Lobbies disappearing unexpectedly

• Solution: Adjust LOBBY_CLEANUP_INTERVAL and LOBBY_CLEANUP_PLAYER_INACTIVITY_THRESHOLD to higher values if lobbies are cleaning up too quickly.

4. Docker container exits immediately

• Solution: Check Docker logs: docker logs <container_id>. Ensure PORT environment variable matches the exposed port.

5. High memory usage with many lobbies

• Solution: Each lobby maintains game state in memory. Consider reducing MAX_MAX_PLAYERS or implementing more aggressive cleanup.

6. CORS errors when embedding

• Solution: Set CORS_ALLOWED_ORIGINS to your specific domain instead of *.

7. Game not starting

• Solution: Ensure all players have clicked "Ready". The game requires all players to be ready before starting.

Debug Mode

Enable verbose logging by checking the application logs:

# For binary
./scribblers 2>&1 | tee scribblers.log

# For Docker
docker logs -f scribblers-container

Metrics Monitoring

Access Prometheus metrics at /v1/metrics endpoint. The current implementation is basic but can be extended to include more game-specific metrics.

Community Support

• Discord: https://discord.gg/cE5BKP2UnE
• GitHub Issues: https://github.com/scribble-rs/scribble.rs/issues

Performance Tips

1. Use Docker for consistent environment
2. Place behind a CDN for static assets
3. Monitor /v1/metrics endpoint
4. Adjust lobby cleanup intervals based on usage patterns
5. Consider regional deployments for low latency (as done by community instances)