Browserless Docker for n8n (Puppeteer)

Overview

Browserless is a containerized headless browser service that provides remote access to Chromium through APIs and WebSocket connections. When integrated with n8n, Browserless allows workflows to perform browser automation tasks without installing Chrome or Puppeteer directly on the n8n server.

This architecture is commonly used for:

Web scraping
Automated testing
Screenshot generation
PDF generation
Form automation
Data collection

Architecture Components

1. n8n Workflow Engine

n8n acts as the automation platform that orchestrates the workflow.

Responsibilities:

Receive triggers (Webhook, Schedule, API, etc.)
Execute workflow logic
Send requests to Browserless
Process returned results
Store or forward collected data

2. Browserless Docker Container

Browserless runs inside a Docker container and manages multiple headless Chrome instances.

Responsibilities:

Launch Chromium browsers on demand
Execute Puppeteer scripts
Handle browser sessions
Generate screenshots and PDFs
Return results to n8n

Benefits:

No Chrome installation required
Centralized browser management
Better resource utilization
Easy scaling

3. Puppeteer

Puppeteer is a Node.js library used to control Chromium browsers programmatically.

With Browserless, Puppeteer connects remotely through:

ws://browserless:3000

wss://browserless.example.com

instead of launching a local browser.

4. Target Websites

The websites being automated may include:

E-commerce sites
Dashboards
Login portals
Reporting systems
Public information websites

Browserless opens and interacts with these sites just like a real browser.

How It Works

Step 1: Workflow Trigger

An n8n workflow starts from:

Webhook
Schedule
Manual trigger
Database event
API request

Step 2: Connect to Browserless

n8n sends a request to Browserless through HTTP or WebSocket.

Example:

ws://browserless:3000

Step 3: Launch Headless Chrome

Browserless creates a new Chromium session inside the Docker container.

The browser runs without a graphical user interface (GUI).

Step 4: Execute Puppeteer Script

Puppeteer performs actions such as:

Opening web pages
Clicking buttons
Filling forms
Extracting data
Taking screenshots
Generating PDFs

Example:

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

Step 5: Return Results

Browserless sends the result back to n8n.

Possible outputs:

HTML content
JSON data
Screenshots
PDF files
Extracted text

Step 6: Continue Workflow

n8n can then:

Save data to a database
Send notifications
Upload files to cloud storage
Trigger additional automation

Example Docker Compose

version: "3.8"

services:
  n8n:
    image: n8nio/n8n:latest
    restart: unless-stopped
    ports:
      - "5678:5678"

  browserless:
    image: browserless/chrome:latest
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - MAX_CONCURRENT_SESSIONS=10
      - CONNECTION_TIMEOUT=60000

Start services:

docker compose up -d

Workflow Communication Flow

n8n
 │
 ▼
Browserless
 │
 ▼
Headless Chrome
 │
 ▼
Website
 │
 ▼
Data / Screenshot / PDF
 │
 ▼
Browserless
 │
 ▼
n8n

Common Use Cases

Web Scraping

Collect product information, prices, and content from websites.

Automated Testing

Run browser-based UI tests automatically.

Screenshot Generation

Capture website screenshots on demand.

PDF Export

Convert web pages into PDF documents.

Form Automation

Automatically fill and submit web forms.

Monitoring

Check website availability and content changes.

Advantages

Easy Deployment

Everything runs in Docker containers.

Scalable

Multiple browser sessions can run simultaneously.

Lightweight n8n Server

Chrome does not need to be installed on the n8n host.

Better Security

Browser execution is isolated inside a dedicated container.

Production Ready

Suitable for large-scale automation workloads.

Flexible Integration

Works with:

n8n
Puppeteer
Playwright
Custom applications
API-driven workflows