For AI agents: a documentation index is available at /llms.txt
Skip to main content

Production Best Practices

Production best practices for deploying and managing Browserless Enterprise Docker containers at scale.

Prerequisites
  • A Browserless Enterprise license
  • Docker installed on your infrastructure

Security Hardening​

Use Secrets Management​

Never store sensitive credentials in environment variables or code. Use Docker secrets or a secrets management system:

# Docker Compose with secrets
services:
  browserless:
    image: registry.browserless.io/browserless/browserless/enterprise:latest
    secrets:
      - browserless_key
      - browserless_token
    environment:
      - KEY_FILE=/run/secrets/browserless_key
      - TOKEN_FILE=/run/secrets/browserless_token

secrets:
  browserless_key:
    file: ./secrets/license_key.txt
  browserless_token:
    file: ./secrets/api_token.txt

Network Isolation​

Isolate Browserless containers from external networks and use a reverse proxy for external access:

services:
  browserless:
    networks:
      - internal
    # Don't expose ports externally; use reverse proxy

  nginx:
    networks:
      - internal
      - external
    ports:
      - "443:443"

networks:
  internal:
    internal: true
  external:

Minimize Attack Surface​

Disable unnecessary features to reduce potential security vulnerabilities:

# Disable unnecessary features
-e ALLOW_GET=false \
-e ALLOW_FILE_PROTOCOL=false \
-e ENABLE_CORS=false

Performance Tuning​

Tune concurrency settings​

Match your concurrency settings to your workload patterns and available resources. Key settings include CONCURRENT (active sessions), QUEUED (waiting requests, typically 1.5-2x concurrent), and TIMEOUT (session timeout in milliseconds). See the Configuration Reference for detailed guidance on these settings.

Resource Limits​

Define resource limits to prevent containers from consuming excessive resources:

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

Sizing Guide:

  • Light workload (5-10 concurrent): 2 CPU, 4GB RAM
  • Medium workload (10-20 concurrent): 4 CPU, 8GB RAM
  • Heavy workload (20-50 concurrent): 8+ CPU, 16GB+ RAM

Connection Pooling​

Reuse browser contexts instead of creating new browsers for better performance:

// Good: Reuse browser connection and create multiple pages
const browser = await puppeteer.connect({
  browserWSEndpoint: 'ws://localhost:3000?token=your-token-here'
});
const page1 = await browser.newPage();
const page2 = await browser.newPage();

// Avoid: Creating new browser connections repeatedly
// const browser1 = await puppeteer.connect(...);
// const browser2 = await puppeteer.connect(...);

Queue Rejection Behavior​

When QUEUED is set to 0, any request that arrives while all CONCURRENT slots are occupied is immediately rejected with HTTP 429. Set QUEUED to a value greater than 0 (e.g., 10, the default) to absorb traffic bursts.

Health Check Threshold Behavior​

MAX_MEMORY_PERCENT and MAX_CPU_PERCENT (when HEALTH=true) only reject new incoming sessions. Running sessions continue until they finish or time out. If memory exceeds the threshold from a running session, the OS OOM killer may terminate the container. Set thresholds conservatively (e.g., 80) to leave headroom.

Scaling Out vs Scaling Up​

When you need more capacity, add more containers behind a load balancer rather than increasing CONCURRENT on a single instance. Each Chrome process competes for CPU and memory. See the NGINX Load Balancing guide.

Performance Tips​

  • Use --shm-size=2g (or shm_size: '2g' in Compose) to give Chrome enough shared memory in containers. Avoid the --disable-dev-shm-usage Chrome flag, which forces Chrome to write to /tmp instead of /dev/shm and can degrade performance.
  • Enable HEALTH checks to prevent overload (reject requests when resources are high)
  • Monitor /pressure endpoint to track system load
  • Use headless mode (default) for better performance

Monitoring & Observability​

Health Checks​

Implement Docker health checks using the /pressure endpoint to monitor container availability and resource usage. Configure the HEALTH environment variable to enable pre-request health checks that reject requests when CPU or memory thresholds are exceeded. See the Configuration Reference for all health check options.

Metrics Collection​

Persist metrics for long-term analysis and alerting:

# Persist metrics
-e METRICS_JSON_PATH=/metrics/metrics.json \
-v ./metrics:/metrics

# Query metrics endpoint
curl http://localhost:3000/metrics

Key Metrics to Monitor:

  • Session metrics: Total sessions, successful, failed, timeouts
  • Queue metrics: Queue depth, queue wait time, rejections
  • Resource metrics: CPU usage, memory usage, disk usage
  • Performance metrics: Average session duration, p95/p99 latency

Webhook Monitoring​

Configure webhooks to receive real-time alerts for critical events like queuing, timeouts, errors, and health failures. See the Webhooks guide for complete configuration details and payload examples.

Logging Best Practices​

Configure appropriate logging levels for production:

# Production: Minimal logging
-e DEBUG=browserless:*

# Debugging: Verbose logging (temporary only)
-e DEBUG=*

# Turn off debug logs
-e DEBUG=-*
warning

Avoid running DEBUG=* in production as it generates excessive logs and impacts performance.

High Availability​

Multi-Instance Deployment​

Deploy multiple Browserless containers behind a load balancer for redundancy and horizontal scale. This architecture provides:

  • High availability: Automatic failover if an instance becomes unhealthy
  • Load distribution: Balance traffic across instances based on connection count or other metrics
  • Zero downtime deployments: Update instances one at a time without service interruption
  • Horizontal scaling: Add capacity by deploying more instances

For complete setup instructions including Docker Compose configurations, NGINX setup, health checks, and SSL configuration, see the NGINX Load Balancing guide.

Auto-Scaling Strategies​

Horizontal Scaling:

  • Monitor queue depth via /pressure endpoint
  • Scale up when queue is consistently high
  • Scale down when instances are underutilized

Vertical Scaling:

  • Increase CONCURRENT setting when adding resources
  • Monitor CPU/memory to determine when to scale vertically

Kubernetes Auto-Scaling:

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: browserless-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: browserless
  minReplicas: 2
  maxReplicas: 10
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 70

Data Persistence​

Volume Management​

Define volumes for persistent data:

volumes:
  # User data (cookies, local storage)
  - browserless_data:/user_data

  # Downloaded files
  - browserless_downloads:/downloads

  # Metrics history
  - browserless_metrics:/metrics

  # Custom fonts
  - ./fonts:/usr/share/fonts/custom:ro

volumes:
  browserless_data:
    driver: local
  browserless_downloads:
    driver: local
  browserless_metrics:
    driver: local

Backup Strategy​

Implement regular backups for important data:

# Backup metrics
docker cp browserless:/metrics/metrics.json ./backups/metrics-$(date +%Y%m%d).json

# Backup user data
docker run --rm -v browserless_data:/data -v $(pwd)/backups:/backup \
  alpine tar czf /backup/user-data-$(date +%Y%m%d).tar.gz /data

Backup Schedule Recommendations:

  • Metrics: Daily backups, retain 30 days
  • User data: Weekly backups, retain 4 weeks
  • Configuration: On every change, version controlled

Disaster Recovery​

Prepare for disaster recovery:

  1. Document your setup: Keep docker-compose files and configurations in version control
  2. Test restores regularly: Verify backups can be restored successfully
  3. Have fallback instances: Keep standby instances in different regions/zones
  4. Monitor external dependencies: Track docker registry availability

CI/CD Integration​

Automated Testing​

Test Browserless integration in your CI pipeline:

# GitHub Actions example
jobs:
  test:
    runs-on: ubuntu-latest
    services:
      browserless:
        image: registry.browserless.io/browserless/browserless/enterprise:latest
        ports:
          - 3000:3000
        env:
          TOKEN: test-token
    steps:
      - name: Run browser tests
        run: npm test
        env:
          BROWSERLESS_URL: ws://localhost:3000

Deployment Pipeline​

Implement a safe deployment pipeline:

  1. Pull new image in staging environment
  2. Run smoke tests against staging
  3. Rolling update in production (one instance at a time)
  4. Monitor metrics after deployment
  5. Rollback if issues detected

Configuration Management​

Use environment-specific configurations:

# Use different env files per environment
docker run --env-file .env.production ...   # Production
docker run --env-file .env.staging ...      # Staging
docker run --env-file .env.development ...  # Development

Summary Checklist​

Before going to production, ensure:

  • Secrets are managed securely (not in plaintext)
  • Network isolation is configured
  • Resource limits are set appropriately
  • Health checks are enabled
  • Monitoring and alerting are configured
  • Multiple instances are deployed (HA)
  • Load balancer is configured with health checks
  • Data volumes are backed up regularly
  • Disaster recovery plan is documented
  • CI/CD pipeline includes Browserless tests
  • Documentation is updated for your team

FAQ & Troubleshooting​

How do I get an Enterprise license?

Contact sales@browserless.io or visit the pricing page for Enterprise plan details.

Can I run Browserless on my own infrastructure?

Yes. Enterprise customers can self-host using the Docker image. See Docker deployment for setup instructions.

Next steps​

Docker deployment

self-host Browserless with Docker

Launch parameters

configure your Enterprise deployment

Was this page helpful?