DOCKER_README.md

🐳 LeRobot Arena Docker Setup

This Docker setup provides a containerized environment that runs both the Python backend and Svelte frontend for LeRobot Arena using modern tools like Bun, uv, and box-packager.

🚀 Quick Start

Using Docker Compose (Recommended)

# Build and start both services
docker-compose up --build

# Or run in detached mode
docker-compose up -d --build

Using Docker directly

# Build the image
docker build -t lerobot-arena .

# Run the container
docker run -p 8080:8080 -p 7860:7860 lerobot-arena

🌐 Access the Application

After starting the container, you can access:

• Frontend (Svelte): http://localhost:7860
• Backend (Python/FastAPI): http://localhost:8080
• Backend API Docs: http://localhost:8080/docs

📋 What's Included

The Docker container includes:

1. Frontend:

   • Svelte application built as static files using Bun
   • Served on port 7860 using Python's built-in HTTP server
   • Production-ready build with all optimizations

2. Backend:

   • FastAPI Python server with dependencies managed by uv
   • Standalone executable created with box-packager for faster startup
   • WebSocket support for real-time robot communication
   • Runs on port 8080
   • Auto-configured for container environment

🛠️ Development vs Production

Production (Default)

The Dockerfile builds the Svelte app as static files using Bun and packages the Python backend as a standalone executable using box-packager.

Development

For development with hot-reload, you can use local tools:

# Terminal 1: Frontend development
bun run dev

# Terminal 2: Backend development
cd src-python && python start_server.py

📁 Container Structure

/home/user/app/
├── src-python/          # Python backend source
│   └── target/release/  # Box-packager standalone executable
├── static-frontend/     # Built Svelte app (static files)
└── start_services.sh    # Startup script for both services

🔧 Build Process

The Docker build process includes these key steps:

1. Frontend Build Stage (Bun):

   • Uses oven/bun:1-alpine for fast package management
   • Builds Svelte app with bun run build
   • Produces optimized static files

2. Backend Build Stage (Python + Rust):

   • Installs Rust/Cargo for box-packager
   • Uses uv for fast Python dependency management
   • Packages backend with box package into standalone executable
   • Configures proper user permissions for HF Spaces

3. Runtime:

   • Runs standalone executable (faster startup)
   • Serves frontend static files
   • Both services managed by startup script

🚀 Performance Benefits

Box-packager Advantages:

• Faster startup: No Python interpreter overhead
• Self-contained: All dependencies bundled
• Smaller runtime: No need for full Python environment
• Cross-platform: Single executable works anywhere

Build Optimization:

• Bun: Faster JavaScript package manager and bundler
• uv: Ultra-fast Python package manager
• Multi-stage build: Minimal final image size
• Alpine base: Lightweight frontend build stage

🔧 Customization

Environment Variables

You can customize the container behavior using environment variables:

docker run -p 8080:8080 -p 7860:7860 \
  -e PYTHONUNBUFFERED=1 \
  -e NODE_ENV=production \
  lerobot-arena

Port Configuration

To use different ports:

# Map to different host ports
docker run -p 9000:8080 -p 3000:7860 lerobot-arena

Then access:

• Frontend: http://localhost:3000
• Backend: http://localhost:9000

Volume Mounts for Persistence

# Mount data directory for persistence
docker run -p 8080:8080 -p 7860:7860 \
  -v $(pwd)/data:/home/user/app/data \
  lerobot-arena

🐛 Troubleshooting

Container won't start

# Check logs
docker-compose logs lerobot-arena

# Or for direct docker run
docker logs <container-id>

Port conflicts

# Check what's using the ports
lsof -i :8080
lsof -i :7860

# Kill processes or use different ports
docker run -p 8081:8080 -p 7861:7860 lerobot-arena

Frontend not loading

# Verify the frontend was built correctly
docker exec -it <container-id> ls -la /home/user/app/static-frontend

# Check if frontend server is running
docker exec -it <container-id> ps aux | grep python

Backend API errors

# Check if standalone executable is running
docker exec -it <container-id> ps aux | grep lerobot-arena-server

# Test backend directly
curl http://localhost:8080/

Box-packager Build Issues

# Force rebuild without cache to fix cargo/box issues
docker-compose build --no-cache
docker-compose up

# Check if Rust/Cargo is properly installed
docker exec -it <container-id> cargo --version

🔄 Updates and Rebuilding

# Pull latest code and rebuild
git pull
docker-compose down
docker-compose up --build

# Force rebuild without cache
docker-compose build --no-cache
docker-compose up

🚀 Hugging Face Spaces Deployment

This Docker setup is optimized for Hugging Face Spaces:

Key Features for HF Spaces:

• Port 7860: Uses the default HF Spaces port
• User permissions: Runs as user ID 1000 as required
• Proper ownership: All files owned by the user
• Git support: Includes git for dependency resolution
• Standalone executable: Faster cold starts on HF infrastructure

Deployment Steps:

1. Push your code to a GitHub repository
2. Create a new Space on Hugging Face Spaces
3. Connect your GitHub repository
4. The YAML frontmatter in README.md will auto-configure the Space
5. HF will build and deploy your Docker container automatically

Accessing on HF Spaces:

• Your Space URL will serve the frontend directly
• Backend API will be available at your-space-url/api/ (if using a reverse proxy)

🔧 Advanced Configuration

Using with nginx (Production)

server {
    listen 80;
    
    # Serve frontend
    location / {
        proxy_pass http://localhost:7860;
    }
    
    # Proxy API calls
    location /api/ {
        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_cache_bypass $http_upgrade;
    }
    
    # WebSocket support
    location /ws/ {
        proxy_pass http://localhost:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

📊 Container Stats

# Monitor resource usage
docker stats lerobot-arena

# View container info
docker inspect lerobot-arena

🧹 Cleanup

# Stop and remove containers
docker-compose down

# Remove images
docker rmi lerobot-arena

# Clean up unused images and containers
docker system prune -a

---

Happy containerized robotics! 🤖🐳