Skip to content

Latest commit

 

History

History

docker

README.md

Docker Deployment

For Fingerprint Protection and Privacy Research. Refer to the project Legal Disclaimer and Responsible Use Guidelines when deploying containers.

This guide explains how to deploy BotBrowser using Docker and Docker Compose for authorized fingerprint protection validation.

Directory Structure

repo-root/
├── docker/
│   ├── Dockerfile
│   ├── docker-compose.yml
│   └── profiles/
│       └── your-profile.enc
├── user-data-dir/      # Persisted browser data
└── ...
  • Dockerfile: Builds the BotBrowser image
  • docker-compose.yml: Defines services, ports, and volumes
  • profiles/: Place your encrypted profiles (.enc) here
  • user-data-dir/: Host folder for cookies, cache, and session data

Prerequisites

  • Docker Engine >= 20.10
  • Docker Compose >= 1.27
  • A BotBrowser .enc profile file

Tip: Run docker version and docker-compose version to verify your setup.

Configuration

  1. Profile

    • Copy your .enc file into docker/profiles/
    • Update PROFILE_NAME or volume mapping in docker-compose.yml

  2. Port

    • Default: 9222
    • Edit the ports section in docker-compose.yml to change

  3. Volumes

    • ./user-data-dir/: Persists browser data
    • ./docker/profiles/: Provides profiles to the container

Quick Start

From the project root:

cd docker
docker-compose up --build -d

To view logs:

docker-compose logs -f botbrowser

Connecting to BotBrowser

Chrome DevTools

  1. Open Chrome or Chromium
  2. Go to chrome://inspect
  3. Click Configure... and add localhost:9222
  4. Find your BotBrowser instance under Remote Target

Integration Examples

⚠️ Integration examples with Playwright and Puppeteer are for fingerprint protection and privacy research only. Unauthorized scraping or production misuse is prohibited.

Playwright

const { chromium } = require('playwright');
(async () => {
  const browser = await chromium.connectOverCDT('ws://localhost:9222');
  const page = await browser.newPage();
  // ...
})();

Puppeteer

const puppeteer = require('puppeteer');
(async () => {
  const browser = await puppeteer.connect({
    browserWSEndpoint: 'ws://localhost:9222'
  });
  const page = await browser.newPage();
  // ...
})();

Note: These scripts are not intended for bulk data collection and must only be run in explicitly authorized test setups.

Environment Variables

Set in docker-compose.yml:

services:
  botbrowser:
    environment:
      - PORT=9222
      - PROFILE_NAME=your-profile.enc

Troubleshooting

Issue Solution
Container won't start Check profile file exists and permissions
Port conflict Change port mapping in docker-compose.yml
Data persistence issue Ensure user-data-dir is writable

For other issues, see the main README or open a GitHub issue.

Examples

Example Directory Description
Cloudflare Reverse proxy test (Cloudflare) with Docker
Wizzair Airline website compatibility demo with Docker
Virgin Australia JFK→BOS GraphQL capture demo (profiles, per-launch proxy)

Legal Disclaimer & Terms of Use • Responsible Use Guidelines. BotBrowser is for authorized fingerprint protection and privacy research only.