High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
Docker Local Testing
This page is a practical checklist for testing the current Docker setup locally.
It covers two paths:
- the default managed-config flow, where the container owns
/data/.pinchtab/config.json(HOME=/data; on Linux the default config lives under~/.pinchtab) - the explicit-config flow, where you mount your own
config.jsonand setPINCHTAB_CONFIG
Managed Config Flow
Build and start the local Compose service:
docker compose up --build -d
docker compose logs -f pinchtab
Inspect the effective config path and persisted config:
docker exec pinchtab pinchtab config path
docker exec pinchtab sh -lc 'cat /data/.pinchtab/config.json'
Expected results:
- the config path is
/data/.pinchtab/config.json server.bindin the persisted config is0.0.0.0(the entrypoint sets it so port publishing works)- a token is present if one was generated on first boot or passed in
Verify the config bind address:
docker exec pinchtab pinchtab config get server.bind
Expected result: 0.0.0.0 (set by entrypoint on first boot)
Verify persistence across restart:
docker compose down
docker compose up -d
docker exec pinchtab sh -lc 'cat /data/.pinchtab/config.json'
Explicit PINCHTAB_CONFIG Flow
Create a local config file, for example ./tmp/config.json:
{
"server": {
"bind": "0.0.0.0",
"port": "9867",
"token": "local-test-token"
}
}
Run the container with that config mounted read-only (to test a local build instead of the published image, first run docker build -t pinchtab/pinchtab .):
docker run --rm -d \
--name pinchtab-test \
-p 127.0.0.1:9867:9867 \
-e PINCHTAB_CONFIG=/config/config.json \
-v "$PWD/tmp/config.json:/config/config.json:ro" \
-v pinchtab-data:/data \
--shm-size=2g \
pinchtab/pinchtab
Verify the explicit config path and auth:
docker exec pinchtab-test pinchtab config path
docker exec pinchtab-test sh -lc 'cat /config/config.json'
curl -H 'Authorization: Bearer local-test-token' http://127.0.0.1:9867/health
Expected results:
pinchtab config pathreports/config/config.json- the mounted file is used as-is
- the container entrypoint does not rewrite the custom config
What To Check When Something Fails
Container logs:
docker logs pinchtab
docker logs pinchtab-test
Config path:
docker exec pinchtab pinchtab config path
docker exec pinchtab-test pinchtab config path
Persisted config content:
docker exec pinchtab sh -lc 'cat /data/.pinchtab/config.json'
Automated Docker E2E
The E2E stack (tests/e2e/docker-compose.yml, tests/e2e/docker-compose-multi.yml) builds this same Dockerfile and runs docker-entrypoint.sh, but always with PINCHTAB_CONFIG set — so it exercises the explicit-config flow only. The managed-config flow above is covered only by this manual checklist.
./dev e2e # extended suite (go run ./tests/tools/runner e2e --suite extended)
./dev e2e smoke # smoke tier
./dev e2e api <text> # one suite, filtered by scenario file name (--suite api --filter <text>)
./dev e2e test "<name>" # runs only the first start_test whose name contains <name>
Current Caveats
The Docker runtime path owns --no-sandbox compatibility now (added at launch when a container is detected). Do not put it in browser.extraFlags; config validation rejects it.
docker-entrypoint.sh checks for an existing config at $XDG_CONFIG_HOME/pinchtab/config.json (/data/.config/...), but the binary reads and writes /data/.pinchtab/config.json, so the "first boot" block runs on every start: server.bind is re-set to 0.0.0.0 and, when PINCHTAB_TOKEN is set, server.token is overwritten with it.