> ## Documentation Index
> Fetch the complete documentation index at: https://docs.springwinter.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Deploy a Puppeteer Browser Worker on Springwinter

> Package Puppeteer and Chrome for a Springwinter Worker, manage browser processes and memory, and understand Fargate sandbox limits before visiting untrusted sites.

A Puppeteer Worker can process screenshot, PDF, testing, and trusted automation jobs from a queue. The difficult part is not starting Chrome; it is process cleanup, memory control, and browser sandboxing.

*Updated October 9, 2026.*

**Use Springwinter for trusted browser automation only after validating the Chrome security model on Fargate.**

## Package matching browser versions

Pin Puppeteer and the browser together. The official Puppeteer image includes Chrome for Testing and required libraries, but its documented sandboxed mode requires the `SYS_ADMIN` Linux capability.

AWS Fargate does not allow adding `SYS_ADMIN`. Running Chrome with `--no-sandbox` removes an important security boundary and is not appropriate for hostile pages or multi-tenant browsing.

For trusted internal pages, build and test a dedicated image. For untrusted sites, use a browser platform with a supported sandbox or a stronger isolated runtime.

## Worker process model

Use one long-lived Node.js process, a bounded browser pool, and a strict maximum number of pages per browser. Recycle browsers after a job count, memory threshold, crash, or timeout.

Each job should:

1. Validate the URL and operation.
2. Enforce an allowlist when possible.
3. Create a fresh incognito browser context.
4. Set navigation, request, and total job timeouts.
5. Block unnecessary downloads and resource types.
6. Upload output to S3.
7. Close the page and context in `finally`.
8. Restart the browser after any uncertain failure.

## Deploy as a Springwinter Worker

Select a memory size based on concurrent pages, not only Node.js heap use. Chrome uses multiple child processes and shared memory outside V8. Begin with one browser and one page per container, then measure.

Send structured logs to stdout. Record target hostname, duration, browser exit code, timeout category, output size, and memory pressure without logging sensitive page content.

## Shutdown behavior

When the Worker receives `SIGTERM`, stop accepting jobs, close pages and browser processes, and leave unfinished queue messages unacknowledged. Use an init process in the image when supported so orphaned Chrome children are reaped.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can Puppeteer run on AWS Fargate?">
    Headless Chrome can run on Fargate, but the secure sandbox configuration is the key constraint. Fargate cannot add `SYS_ADMIN`, while disabling Chrome's sandbox weakens isolation. Test the exact browser, image, flags, and threat model.
  </Accordion>

  <Accordion title="Why does Puppeteer consume so much memory?">
    Chrome uses several processes for browser, renderer, network, and utility work. Multiple pages, large images, PDFs, JavaScript-heavy sites, and leaked contexts increase memory beyond the Node.js heap.
  </Accordion>

  <Accordion title="Should one browser handle every job forever?">
    No. Reuse can improve latency, but browsers accumulate state and may leak resources. Recycle after bounded use and create a fresh isolated context for each job.
  </Accordion>
</AccordionGroup>

## Sources and further reading

* [Puppeteer Docker guide](https://pptr.dev/guides/docker)
* [Fargate security considerations](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/fargate-security-considerations.html)
* [Springwinter Workers](/deploy/workers)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.