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.

## 🏗️ Architecture

The application consists of:
- **Svelte Frontend**: Built as static files and served by FastAPI
- **FastAPI Backend**: WebSocket server with HTTP API for robot control
- **Single Port**: Both frontend and backend served on port 7860

## 🚀 Quick Start

### Build and Run with Docker

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

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

# Access the application
open http://localhost:7860
```

### Using Docker Compose

```bash
# Start the application
docker-compose up

# Access the application
open http://localhost:7860
```

## 🌐 Deployment

### Hugging Face Spaces

This project is configured for deployment on Hugging Face Spaces:

1. Push to a Hugging Face Space repository
2. The Dockerfile will automatically build and serve the application
3. Both frontend and backend run on port 7860 (HF Spaces default)
4. Environment detection automatically configures URLs for HF Spaces

### Local Development vs Production

- **Local Development**: Frontend dev server on 5173, backend on 7860
- **Docker/Production**: Both frontend and backend served by FastAPI on 7860
- **HF Spaces**: Single FastAPI server on 7860 with automatic HTTPS and domain detection

## 🔧 Environment Variables

- `SPACE_HOST`: Set automatically by Hugging Face Spaces for proper URL configuration
- `PORT`: Override the default port (7860)

## 📡 API Endpoints

- **Frontend**: `http://localhost:7860/` (Served by FastAPI)
- **API**: `http://localhost:7860/api/*`
- **WebSocket**: `ws://localhost:7860/ws/*`
- **Status**: `http://localhost:7860/status`

## 🛠️ Development

For local development without Docker:

```bash
# Start backend
cd src-python
uv sync
uv run python start_server.py

# Start frontend (in another terminal)
bun install
bun run dev
```

The frontend dev server (port 5173) will automatically proxy API requests to the backend (port 7860).

## 📋 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:

```bash
# 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:

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

### Port Configuration

To use different ports:

```bash
# 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

```bash
# 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
```bash
# Check logs
docker-compose logs lerobot-arena

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

### Port conflicts
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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

```bash
# 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)
```nginx
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

```bash
# Monitor resource usage
docker stats lerobot-arena

# View container info
docker inspect lerobot-arena
```

## 🧹 Cleanup

```bash
# 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! 🤖🐳**