Enterprise Deployment Guide

The Browserless Enterprise Docker image provides production-grade browser automation with advanced session management, monitoring, and multi-browser support. This page covers deployment, configuration, and connecting to your instance.

The Enterprise image includes:

• Advanced Session Management: Enhanced queueing, priority handling, and session persistence
• Production Monitoring: Built-in metrics, health checks, and performance tracking
• Enterprise Support: Direct access to our engineering team for deployment assistance
• Custom Features: Session recording, live debugging, and advanced webhook integrations
• License-Based Deployment: Flexible licensing for private deployments without usage-based billing
• Multi-Browser Support: Chrome, Chromium, Firefox, WebKit, and Edge in a single container

Prerequisites

Before deploying the Enterprise image, ensure you have:

1. Docker or Container Runtime: Docker 20.10+, Podman, or Kubernetes
2. Enterprise License Key: Contact sales@browserless.io for a license
3. Registry Credentials: Provided by the Browserless team for accessing our private registry
4. System Resources: Minimum 2 CPU cores and 4GB RAM (see Resource Requirements)

Getting Started

1. Registry Authentication

   Authenticate with the Browserless private registry using credentials provided by our team:

   docker login registry.browserless.io

   Enter your username and password when prompted.

   info

   Your registry credentials are separate from your license key. The credentials grant access to pull the image, while the license key activates the enterprise features at runtime.

2. Pull the Enterprise Image

   Pull the latest enterprise image (supports both ARM64 and AMD64 architectures):

   docker pull registry.browserless.io/browserless/browserless/enterprise:latest

   For production deployments, we recommend pinning to a specific version:

   # Pin to a specific version for stability
   docker pull registry.browserless.io/browserless/browserless/enterprise:2.3.0

3. Quick Start

   Run the enterprise image with minimal configuration:

   docker run \
     --rm \
     -p 3000:3000 \
     -e KEY=your-enterprise-license-key \
     registry.browserless.io/browserless/browserless/enterprise:latest

   Shared memory (/dev/shm)

   Chrome uses /dev/shm for shared memory. In Docker, /dev/shm defaults to 64MB, which can cause Chrome crashes or instability under load. For production workloads, increase shared memory with --shm-size=2g. In some environments, --ipc=host can also help, but it shares the host IPC namespace and may be less desirable from an isolation standpoint.

   Once running, verify the deployment:

   • API Documentation: http://localhost:3000/docs
   • Health Check: http://localhost:3000/pressure
   • Metrics: http://localhost:3000/metrics

Setting Your License Key

Your Enterprise license key (KEY) and API token (TOKEN) are essential for running the Enterprise image. Below are examples showing different ways to configure these variables. For detailed information on these and other configuration options, see the Configuration Reference.

Docker Run

docker run \
  -e KEY=your-enterprise-license-key \
  -e TOKEN=your-secure-api-token \
  -p 3000:3000 \
  registry.browserless.io/browserless/browserless/enterprise:latest

Environment File

Create a .env file:

KEY=your-enterprise-license-key
TOKEN=your-secure-api-token
CONCURRENT=20

Run with the env file:

docker run --env-file .env -p 3000:3000 \
  registry.browserless.io/browserless/browserless/enterprise:latest

Docker Compose

services:
  browserless:
    image: registry.browserless.io/browserless/browserless/enterprise:latest
    environment:
      - KEY=${BROWSERLESS_LICENSE_KEY}
      - TOKEN=${BROWSERLESS_API_TOKEN}
    ports:
      - "3000:3000"

Production Deployment

For production deployments, it's essential to configure the Enterprise image for performance, security, and reliability. Below are recommended configurations and best practices.

Docker Compose (Recommended)

For production deployments, we recommend using Docker Compose with comprehensive configuration:

Production Setup

---
services:
  browserless:
    image: registry.browserless.io/browserless/browserless/enterprise:2.3.0
    container_name: browserless-enterprise
    restart: unless-stopped

    environment:
      # License & Authentication
      - KEY=${BROWSERLESS_LICENSE_KEY}
      - TOKEN=${BROWSERLESS_API_TOKEN}

      # Performance & Scaling
      - CONCURRENT=20
      - QUEUED=30
      - TIMEOUT=300000

      # Storage & Persistence
      - DOWNLOAD_DIR=/downloads
      - DATA_DIR=/user_data
      - METRICS_JSON_PATH=/metrics/metrics.json

      # Security
      - ENABLE_CORS=false
      - ALLOW_GET=false
      - ALLOW_FILE_PROTOCOL=false

      # Health & Monitoring
      - HEALTH=true
      - MAX_MEMORY_PERCENT=90
      - MAX_CPU_PERCENT=90

      # Logging
      - DEBUG=browserless*
      - TZ=America/New_York

    ports:
      - "3000:3000"

    volumes:
      - ./downloads:/downloads
      - ./user_data:/user_data
      - ./metrics:/metrics
      - ./fonts:/usr/share/fonts/custom

    # Increase shared memory from Docker's 64MB default to prevent Chrome crashes under load
    shm_size: '2g'
    # Cap container log size to prevent disk exhaustion
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "5"

    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/pressure"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

    deploy:
      resources:
        limits:
          cpus: '4'
          memory: 8G
        reservations:
          cpus: '2'
          memory: 4G

High Availability

---
services:
  browserless-1:
    image: registry.browserless.io/browserless/browserless/enterprise:2.3.0
    environment:
      - KEY=${BROWSERLESS_LICENSE_KEY}
      - TOKEN=${BROWSERLESS_API_TOKEN}
      - CONCURRENT=20
      - HEALTH=true
    ports:
      - "3001:3000"
    restart: unless-stopped
    deploy:
      resources:
        limits:
          memory: 8G
        reservations:
          memory: 4G

  browserless-2:
    image: registry.browserless.io/browserless/browserless/enterprise:2.3.0
    environment:
      - KEY=${BROWSERLESS_LICENSE_KEY}
      - TOKEN=${BROWSERLESS_API_TOKEN}
      - CONCURRENT=20
      - HEALTH=true
    ports:
      - "3002:3000"
    restart: unless-stopped
    deploy:
      resources:
        limits:
          memory: 8G
        reservations:
          memory: 4G

  # Load balancer (nginx)
  nginx:
    image: nginx:alpine
    ports:
      - "3000:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    depends_on:
      - browserless-1
      - browserless-2
    restart: unless-stopped

With Webhooks

---
services:
  browserless:
    image: registry.browserless.io/browserless/browserless/enterprise:2.3.0
    environment:
      - KEY=${BROWSERLESS_LICENSE_KEY}
      - TOKEN=${BROWSERLESS_API_TOKEN}
      - CONCURRENT=15

      # Webhook Alerts
      - QUEUE_ALERT_URL=https://your-monitoring.com/webhooks/queue
      - REJECT_ALERT_URL=https://your-monitoring.com/webhooks/reject
      - TIMEOUT_ALERT_URL=https://your-monitoring.com/webhooks/timeout
      - FAILED_HEALTH_URL=https://your-monitoring.com/webhooks/health

    ports:
      - "3000:3000"
    restart: unless-stopped

Resource Requirements

Recommended specifications based on workload:

Workload	CPU Cores	Memory	Concurrent Sessions	Storage
Light (Development)	2	4GB	5-10	10GB
Medium (Production)	4	8GB	10-20	50GB
Heavy (Enterprise)	8+	16GB+	20-50	100GB+

Connecting to Your Enterprise Instance

Once your Enterprise instance is running, connect using your preferred method. Below are examples for Puppeteer, Playwright, and the REST API.

Local Network (No Token)

For applications on the same private network, you can connect without a token:

Puppeteer

const puppeteer = require('puppeteer-core');

let browser;
try {
  browser = await puppeteer.connect({
    browserWSEndpoint: 'ws://localhost:3000/chromium'
  });

  const page = await browser.newPage();
  await page.goto('https://example.com');
  const screenshot = await page.screenshot();

  // Use screenshot...
} catch (error) {
  console.error('Browser automation failed:', error);
} finally {
  if (browser) {
    await browser.close();
  }
}

Playwright

const { chromium } = require('playwright');

let browser;
try {
  browser = await chromium.connectOverCDP('ws://localhost:3000/chromium');
  const context = await browser.newContext();
  const page = await context.newPage();

  await page.goto('https://example.com');
  const screenshot = await page.screenshot();

  // Use screenshot...
} catch (error) {
  console.error('Browser automation failed:', error);
} finally {
  if (browser) {
    await browser.close();
  }
}

REST API

# Screenshot API
curl -X POST http://localhost:3000/screenshot \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}' \
  --output screenshot.png

# Content API
curl -X POST http://localhost:3000/content \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

External Access (With Token)

For production deployments with external access, always use token authentication:

Puppeteer

const puppeteer = require('puppeteer-core');

let browser;
try {
  browser = await puppeteer.connect({
    browserWSEndpoint: 'ws://browserless.company.com:3000/chromium?token=YOUR_API_TOKEN'
  });

  const page = await browser.newPage();
  await page.goto('https://example.com');
  const data = await page.screenshot();

  return data;
} catch (error) {
  console.error('Browser connection failed:', error);
  throw error;
} finally {
  if (browser) {
    await browser.close();
  }
}

Playwright

const { chromium } = require('playwright');

let browser;
try {
  browser = await chromium.connectOverCDP(
    'ws://browserless.company.com:3000/chromium?token=YOUR_API_TOKEN'
  );

  const context = await browser.newContext();
  const page = await context.newPage();
  await page.goto('https://example.com');

  const screenshot = await page.screenshot();
  return screenshot;
} catch (error) {
  console.error('Browser connection failed:', error);
  throw error;
} finally {
  if (browser) {
    await browser.close();
  }
}

REST API

# Via query parameter
curl -X POST "http://browserless.company.com:3000/screenshot?token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}' \
  --output screenshot.png

# Via header (recommended)
curl -X POST http://browserless.company.com:3000/screenshot \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{"url": "https://example.com"}' \
  --output screenshot.png

Configuration Options

The Enterprise image supports extensive configuration through environment variables. For a comprehensive list of all available options including license settings, performance tuning, security, health monitoring, webhooks, and more, see the Docker Configuration Reference.

For multi-user deployments, see Token Roles to set up role-based access control with admin, developer, and viewer permissions.

Production Deployment Checklist

Before deploying to production, review these essential guides:

• Best Practices - Security hardening, performance tuning, monitoring, high availability, and data persistence strategies
• NGINX Load Balancing - Set up load balancing for high availability deployments
• Webhooks - Configure event notifications and alerting