remote-chrome

Run a shared Chrome for bidi2pdf

bidi2pdf talks to chromedriver over HTTP and WebDriver BiDi. A chromedriver container that several processes share is cheaper and more predictable than a browser per process, and keeps Chrome out of the application's own container.

Does not: cover Kubernetes or a cloud browser service, and does not make an untrusted page safe on its own (section 5 is what it takes).

Ground rules

• bidi2pdf is the renderer. If it fails, report its error.code, error.hint and exit code; never make the PDF or screenshot another way (Chrome's own print-to-PDF, another PDF engine).
• Install nothing unasked. Name what is missing and suggest a way (the render-pdf skill's preflight); run nothing that changes the system without the user's yes.
• bidi2pdf's results first. Read its --json result instead of inspecting the PDF with other tools.

1. The container

references/compose.remote-chrome.yml is a working Compose service, taken from an application that runs it in development and production. The parts that matter, and why:

• Image dieters877565/chromedriver (chromedriver + Chromium, hyphenation dictionaries included). It answers on port 3000; the new-session URL is http://<service>:3000/session.
• No published port, an internal network only. Whoever reaches port 3000 drives a browser: keep it to the containers that render. No VNC (ENABLE_VNC: "false").
• Chrome's sandbox needs to create namespaces, which Docker's default seccomp profile only allows with CAP_SYS_ADMIN. Three ways, from the narrowest:
  1. The gem's seccomp profile docker/chrome-driver/chrome.json (security_opt: ["seccomp=chrome.json"]), no extra capability. It allows the namespace calls Chrome uses, but also some Docker's default refuses (mount, bpf, ptrace, perf_event_open); verify on your host that sessions start before relying on it.
  2. cap_add: [SYS_ADMIN] - works with the default profile, and is what the reference file uses. It is a broad capability: keep the container on its internal network and give it nothing else.
  3. No extra capability, and every client passes --no-sandbox (DISABLE_CHROME_SANDBOX=true for the CLI). Chrome then runs every page without its own sandbox - only for pages you trust. Some CI runners drop --cap-add silently; there only this works.
• Limits from measurement, not guesses: one Chrome session runs ~110 threads (Docker counts them as pids) and a few hundred MB. pids_limit: 1024, mem_limit: 2g with memswap_limit equal (no swap: a Chrome out of memory is killed and replaced instead of freezing every render), shm_size: 256m. At 512 pids and 1 GB, four concurrent renders crashed or froze it.
• WATCHDOG_ENABLED: "true" stops chromedriver when it stops answering or memory thrashes; restart: unless-stopped then starts a fresh container. The image's health check (/status) only marks it unhealthy - Docker never restarts an unhealthy container by itself.
• LANG/LANGUAGE set the browser's locale: date and number formats in form fields follow it.