docs/guides/docker.md

Docker Deployment

PinchTab can run in Docker with a mounted data volume for config, profiles, and state. The bundled image now manages its default config under /data/.config/pinchtab/config.json. If you want full control over the config file path, you can still mount your own file and point PINCHTAB_CONFIG at it.

Quick Start

Build the image from this repository:

docker build -t pinchtab .

Run the container with a persistent data volume:

docker run -d \
  --name pinchtab \
  -p 127.0.0.1:9867:9867 \
  -v pinchtab-data:/data \
  --shm-size=2g \
  pinchtab

On first boot, the image creates /data/.config/pinchtab/config.json with bind: 0.0.0.0 (required for Docker port publishing) and generates a token if needed.

If you inspect the startup security summary from inside Docker, the loopback bind check will still report the effective runtime bind as non-loopback. That is expected: the process is listening on 0.0.0.0 inside the container so Docker port publishing can forward traffic to it.

This does not automatically mean the service is exposed beyond your machine. Host exposure still depends on how you publish the container port. For example:

• -p 127.0.0.1:9867:9867 keeps the service reachable only from the host machine
• -p 9867:9867 exposes it on the host's network interfaces

Treat the Docker runtime bind and the host-published address as separate layers. If you expose PinchTab beyond localhost, keep an auth token set and put it behind TLS or a trusted reverse proxy.

Health Check and Readiness

PinchTab has a two-stage readiness model in Docker:

1. Dashboard ready: /health returns HTTP 200 — the server process is up
2. Browser ready: /health response has defaultInstance.status == "running" — Chrome is ready

Why Two Stages?

With the always-on strategy (default), PinchTab launches a managed Chrome instance at startup. The dashboard becomes healthy immediately, but Chrome takes a few seconds to initialize. If your application hits /navigate or /snapshot before Chrome is ready, it gets HTTP 503.

Docker Compose Healthcheck

The standard healthcheck marks the container as "healthy" when the dashboard responds:

healthcheck:
  test: ["CMD-SHELL", "wget -q -O /dev/null http://localhost:9867/health"]
  interval: 3s
  timeout: 10s
  retries: 20
  start_period: 15s

This is correct for container orchestration — Docker knows the process is alive and the service is reachable.

Application-Level Readiness

If your application needs Chrome to be ready before making requests, poll /health and check for defaultInstance.status:

# Wait for browser to be ready
until curl -sf http://localhost:9867/health | jq -e '.defaultInstance.status == "running"' > /dev/null 2>&1; do
  sleep 1
done
echo "Browser ready"

Or in code:

async function waitForBrowser(baseUrl, timeoutMs = 60000) {
  const start = Date.now();
  while (Date.now() - start < timeoutMs) {
    try {
      const res = await fetch(`${baseUrl}/health`);
      const data = await res.json();
      if (data.defaultInstance?.status === "running") return;
    } catch {}
    await new Promise(r => setTimeout(r, 1000));
  }
  throw new Error("Browser not ready within timeout");
}

Full Health Response (Server Mode)

{
  "status": "ok",
  "mode": "dashboard",
  "version": "0.8.0",
  "uptime": 12345,
  "profiles": 1,
  "instances": 1,
  "defaultInstance": {
    "id": "inst_abc12345",
    "status": "running"
  },
  "agents": 0,
  "restartRequired": false
}

See Health Reference for full details.

Supplying Your Own config.json

If you want to manage the config file yourself, mount it and point PINCHTAB_CONFIG at it:

docker-data/
└── config.json

Example docker-data/config.json:

{
  "server": {
    "bind": "0.0.0.0",
    "port": "9867",
    "stateDir": "/data/state"
  },
  "profiles": {
    "baseDir": "/data/profiles",
    "defaultProfile": "default"
  },
  "instanceDefaults": {
    "mode": "headless",
    "noRestore": true
  }
}

Run with an explicit config file:

docker run -d \
  --name pinchtab \
  -p 127.0.0.1:9867:9867 \
  -e PINCHTAB_CONFIG=/config/config.json \
  -v "$PWD/docker-data:/data" \
  -v "$PWD/docker-data/config.json:/config/config.json:ro" \
  --shm-size=2g \
  pinchtab

Check it:

curl http://localhost:9867/health
curl http://localhost:9867/instances

What To Persist

If you want data to survive container restarts, persist:

• the managed config directory or your mounted config file
• the profile directory
• the state directory

Without a mounted volume, profiles and saved session state are ephemeral.

Runtime Configuration

Supported environment variables:

• PINCHTAB_CONFIG — path to custom config file (if not using managed config)
• PINCHTAB_TOKEN — auth token (prefer Docker secrets; see below)

Everything else, including bind address and port, should go in config.json.

About bind: 0.0.0.0 in Containers

The entrypoint sets bind: 0.0.0.0 in the config on first boot. This is necessary because Docker port publishing requires the process to listen on 0.0.0.0 inside the container.

Example: docker run -p 127.0.0.1:9867:9867 keeps PinchTab reachable only from your host machine, even though the process internally listens on 0.0.0.0.

Docker Secrets (Sensitive Configuration)

For production deployments, use Docker secrets instead of env vars for PINCHTAB_TOKEN:

# Create a secret
echo "your-secret-token" | docker secret create pinchtab_token -

# Use it in docker-compose.yml
services:
  pinchtab:
    image: pinchtab/pinchtab
    secrets:
      - pinchtab_token
    environment:
      PINCHTAB_TOKEN_FILE: /run/secrets/pinchtab_token
    # ... rest of config

Or with docker run:

docker run -d \
  --name pinchtab \
  --secret pinchtab_token \
  -e PINCHTAB_TOKEN_FILE=/run/secrets/pinchtab_token \
  pinchtab/pinchtab

Secrets are mounted read-only and never appear in docker ps or logs.

Compose

The repository includes a docker-compose.yml that follows the managed-config pattern:

1. mount a persistent /data volume
2. let the entrypoint create and maintain /data/.config/pinchtab/config.json
3. optionally pass PINCHTAB_TOKEN

If you prefer a fully user-managed config file, mount it separately and set PINCHTAB_CONFIG.

If you expose PinchTab beyond localhost, set an auth token and put it behind TLS or a trusted reverse proxy.

Security

Chrome Sandbox Disabled in Containers

PinchTab runs Chrome with --no-sandbox in containers. This is standard practice because:

• User namespaces unavailable: Containers don't have the full namespace isolation Chrome's sandbox requires
• Container security compensates: The Docker image uses:
  • cap_drop: ALL (no capabilities)
  • read_only: true (immutable filesystem)
  • seccomp default profile (syscall filtering)
  • Non-root user
• Isolation at container layer: The container runtime (cgroups, seccomp, AppArmor/SELinux) provides the security boundary

This configuration is used by major headless browser services (Puppeteer, Playwright, Browserless).

Resource Notes

Chrome in containers usually needs:

• larger shared memory, such as --shm-size=2g
• enough RAM for your tab count and workload

For heavier scraping or testing workloads, also consider:

• lowering instanceDefaults.maxTabs
• setting block options like blockImages in config
• running multiple smaller containers instead of one oversized browser

Multi-Instance In Containers

You can run orchestrator mode inside one container and start managed instances from the API, but many teams prefer one browser service per container because:

• lifecycle is simpler
• container-level resource limits are clearer
• restart behavior is easier to reason about

Choose based on whether you want container-level isolation or PinchTab-managed multi-instance orchestration.