README.docker.md

🐳 Docker Setup for BrowserPilot

BrowserPilot can be easily deployed using Docker, which provides a consistent environment with all dependencies pre-installed.

Quick Start with Docker

1. Using Docker Compose (Recommended)

The easiest way to run BrowserPilot is with Docker Compose:

# Clone the repository
git clone https://github.com/ai-naymul/BrowserPilot.git
cd BrowserPilot

# Create environment file
echo 'GOOGLE_API_KEY=your_actual_api_key_here' > .env

# Run with Docker Compose
docker-compose up -d

The application will be available at http://localhost:8000.

2. Using Docker Build & Run

If you prefer to use Docker directly:

# Build the image
docker build -t browserpilot .

# Run the container
docker run -d \
  --name browserpilot \
  -p 8000:8000 \
  -e GOOGLE_API_KEY=your_actual_api_key_here \
  -v $(pwd)/outputs:/app/outputs \
  --shm-size=2g \
  browserpilot

Configuration

Environment Variables

Set these environment variables for the container:

# Required
GOOGLE_API_KEY=your_gemini_api_key_here

# Optional - Proxy configuration
SCRAPER_PROXIES='[{"server": "http://proxy1:port", "username": "user", "password": "pass"}]'

Volume Mounts

• ./outputs:/app/outputs - Persist extracted data and downloads
• ./.env:/app/.env:ro - Mount environment file (optional)

Production Deployment

For production use, use the production Docker Compose configuration:

# Production deployment
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d

This provides:

• Resource limits (4GB RAM, 2 CPU cores)
• Proper logging configuration
• Restart policies
• Optimized environment settings

Docker Image Details

Multi-Stage Build

The Dockerfile uses a multi-stage build process:

1. Frontend Builder: Builds the React frontend using Node.js Alpine
2. Runtime: Uses Microsoft's Playwright Python image with all browser dependencies

Features

• ✅ Pre-installed Playwright browsers (Chromium)
• ✅ All system dependencies for browser automation
• ✅ Non-root user for security
• ✅ Health checks included
• ✅ Optimized for container environments

Image Size

The final image is approximately 2.5GB due to:

• Playwright browsers and dependencies
• Python runtime and packages
• System libraries for browser automation

Troubleshooting

Common Issues

Container exits immediately:

# Check logs
docker logs browserpilot

# Common issue: Missing GOOGLE_API_KEY
docker run -e GOOGLE_API_KEY=your_key_here browserpilot

Browser crashes or fails:

# Increase shared memory size
docker run --shm-size=2g browserpilot

# Or with Docker Compose (already configured)
docker-compose up

Permission issues with outputs:

# Fix output directory permissions
sudo chown -R $(id -u):$(id -g) outputs/

Health Checks

The container includes health checks:

# Check container health
docker inspect --format='{{.State.Health}}' browserpilot

Performance Tuning

For better performance:

# Increase resources
docker run \
  --memory=4g \
  --cpus=2 \
  --shm-size=2g \
  browserpilot

Development with Docker

Live Development

For development with live reload:

# Mount source code for development
docker run -it \
  -p 8000:8000 \
  -v $(pwd)/backend:/app/backend \
  -v $(pwd)/outputs:/app/outputs \
  -e GOOGLE_API_KEY=your_key_here \
  browserpilot \
  python -m uvicorn backend.main:app --host 0.0.0.0 --port 8000 --reload

Building Custom Images

To customize the Docker image:

# Extend the base image
FROM browserpilot:latest

# Add custom dependencies
RUN pip install your-custom-package

# Copy custom configurations
COPY custom-config.json /app/

Security Considerations

• The container runs as a non-root user (pwuser)
• Uses security options for browser sandbox
• Environment variables are not exposed in the image
• Secrets should be mounted as files or environment variables

Monitoring and Logging

Logs

# View logs
docker logs -f browserpilot

# With timestamps
docker logs -t browserpilot

Monitoring

# Resource usage
docker stats browserpilot

# Container inspection
docker inspect browserpilot