iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
To run Spatie Browsershot in Laravel Vapor’s Docker deployment mode, your image must provide more than the PHP package: it needs a compatible Node.js runtime, Puppeteer, and a working headless Chrome or Chromium executable, all discoverable by the PHP process. First check the requirements for the Browsershot version your application actually installs, then use Vapor’s current Docker guidance to build and deploy the image. The available Vapor Docker announcement is from 2020, so it is not a reliable source for a current base-image tag or copy-paste Dockerfile.
What has to run for a Browsershot capture
Browsershot is the PHP-facing part of a multi-component rendering stack. Its job is to pass a capture request to Puppeteer; Puppeteer controls headless Google Chrome, which loads the page or supplied HTML and produces an image or PDF. Installing Browsershot with Composer alone does not install or configure a complete browser runtime. See Spatie’s Browsershot introduction.
- Laravel and PHP: your application and the Browsershot package run here.
- Node.js: Puppeteer runs in the Node environment.
- Puppeteer: the browser automation package that Browsershot delegates to.
- Chrome or Chromium: the browser executable Puppeteer launches.
In a self-contained Vapor Docker deployment, these pieces must be compatible and available in the deployed image. A capture can fail even when the Laravel code is correct if Node cannot be started, Puppeteer cannot be resolved, or the browser executable is missing or cannot launch.
Choose where the browser runs
For an in-image setup, package the compatible Node, Puppeteer, and Chrome/Chromium runtime alongside the PHP application in the Vapor Docker image. This keeps the rendering stack with the application deployment, but means your image and build process own the browser dependencies and their compatibility.
#1 Best Overall
Spatie also points to Sidecar Browsershot as an option for AWS Lambda. It is an alternative architecture to assess, not a requirement for Vapor Docker. Compare where Chrome executes, who manages browser and dependency versions, the packaging work, and operational complexity before choosing. AWS documents several general Lambda container-image approaches, but those are not Vapor-specific setup instructions: AWS Lambda Node.js container images.
Configure Vapor Docker without guessing the image
Laravel Vapor is a serverless Laravel deployment platform powered by AWS Lambda, as described in its Vapor introduction. Vapor’s December 2020 Docker deployment announcement describes an environment-specific Dockerfile, setting that environment’s runtime to docker, installing additional libraries or PHP extensions in the Dockerfile, and deploying through Vapor.
That announcement is historical, not current image-tag guidance. Do not copy a base-image tag, PHP version, package-manager command, or Dockerfile from an old example without checking the current Vapor documentation and the conventions for your project. The exact current Vapor base-image tags and Dockerfile requirements are not established here. Once you have confirmed those details for your environment, the image build needs to make the compatible browser runtime available to the PHP application.
Free tools Windows power users keep installed
One-click scans. No signup required.
Check the versions your application needs
Start with the Browsershot major version actually installed in the application; do not assume that the requirements for v4 apply to an older or different major version. Spatie’s surfaced Browsershot v4 requirements specify Node.js 22.0 LTS or higher and Puppeteer 23.0 or higher. Treat these as the documented minimums for the v4 page, not universal requirements for every Browsershot release. Check the installed package and revisit the current requirements page when upgrading.
Rank #2
- Inspect the application’s Composer dependency information to establish which Browsershot version is installed.
- For v4, compare the Node.js and Puppeteer versions provided by your image with the minimums on Spatie’s requirements page.
- Confirm that the Puppeteer installation and the Chrome/Chromium executable available to it are compatible and usable together.
- Repeat the check after changing the Browsershot major version, Node runtime, Puppeteer version, or browser package.
Do not infer compatibility merely because a package installation completed. The useful test is whether the deployed PHP process can invoke Node, resolve Browsershot’s Node-side modules, launch the intended browser, and return a usable output.
Package the runtime and configure executable discovery
After confirming the current Vapor image conventions, install the Node and browser dependencies into the image using the package sources and commands appropriate for that base image. This guide intentionally does not prescribe a Dockerfile or package names: the available Vapor source is a 2020 announcement and does not establish current base-image details. A package name or path that works in one Linux image may not exist in another.
Browsershot documents configuration for the Node environment, Node module path, binary path, Chrome executable path, and Chromium arguments in its requirements documentation. Use these settings when the runtime is installed somewhere other than the defaults or when the PHP process cannot discover it. Set paths to the actual locations in the image you build; do not paste example paths from another distribution as if they were universal.
Recommended Free Tools
Keep the browser runtime and the PHP application’s view of it aligned. A frequent deployment mismatch is installing a Node module or browser in one build stage or location while the running PHP process expects it elsewhere. Verify paths in the final deployed environment, not only on a developer workstation.
Rank #3
Use no-sandbox only as a considered container setting
A restricted container can prevent Chrome from launching with its normal sandbox behavior. Spatie’s Laravel Screenshot driver documentation, which uses Browsershot under the hood, shows a no_sandbox configuration option for Docker or restricted environments: Customizing Browsershot.
Do not treat disabling the sandbox as a universal fix or default. First diagnose the launch error and the constraints of the environment; then assess the security implications for your workload and deployment. If you do apply the option, record why it is needed and test the resulting behavior in the deployed container.
Test the deployed capture path
Use a small, representative capture to validate the entire chain after deployment. Exercise the same code path the application uses and check the returned image or PDF, rather than treating a successful Docker build as proof that Chrome can launch at runtime.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →- Confirm the deployed Browsershot, Node.js, and Puppeteer versions against the applicable requirements.
- Confirm that the PHP process can find the Node binary, required Node modules, and Chrome/Chromium executable.
- Run a capture against a simple page and verify that the expected image or PDF is actually produced.
- Test a representative real target as well; page behavior, loading, and browser launch can differ from a minimal smoke test.
- Check the output destination and permissions in the deployed environment using your application’s configured path. The sources cited here do not establish Vapor-specific writable-path rules or limits.
- Repeat the test after changing the image base, browser, Node, Puppeteer, or Browsershot version.
Troubleshooting common failures
Node cannot be started
Likely cause: Node is absent from the image, the PHP process cannot discover it, or a configured Node path is wrong. Fix: verify the installed runtime in the final image and configure Browsershot’s Node environment or binary path to the actual executable where needed.
Puppeteer or its module cannot be found
Likely cause: the module is not installed where the running process expects it, or the module-path configuration does not match the image. Fix: check the Puppeteer installation and Browsershot’s configured Node module path. Ensure the module is present in the deployed runtime, not just a build environment that is discarded.
Chrome or Chromium executable is missing
Likely cause: the browser was not included in the image, or its path differs from Browsershot’s default. Fix: verify the executable included in your chosen base image and set the Chrome executable path or binary path to its actual location.
The browser is found but fails to launch
Likely cause: incompatible dependencies or a restricted container environment. Fix: check the versions and launch configuration; if the failure points to sandbox restrictions, assess the documented no_sandbox option in the context of your security requirements rather than enabling it automatically.
Captures work locally but not after deployment
Likely cause: local and deployed environments differ in installed versions, executable paths, available browser files, or permissions. Fix: compare the actual deployed runtime and paths with local assumptions, then run the capture through the deployed application process. Confirm the configured output location and that the application can write there.
Best Value
- Docker, Docker Swarm, Docker Compose, Programmer, Developer, Coding, Programming, Software Engineer, Code, DevOps, Deploy, Deployment, Kubernetes, Salt, Puppet, Chef, Terraform, Container, AWS, Azure, Cloud, Geek, Funny, Computer, Software, Tech, IT
- Integration, Scrum, Compile, Compilation, Science, Bug, Debug, Python, Linux, Java, Javascript, Scala, Dotnet, Kotlin
- Lightweight, Classic fit, Double-needle sleeve and bottom hem
The image builds, but rendering is unreliable
Likely cause: build success has only proven that image construction completed; it has not proven that Puppeteer can launch Chrome or that the target page renders correctly. Fix: add a deployed smoke capture and a representative target to release verification. Keep version and path checks part of the process when updating the image.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
If the task is to obtain a website screenshot rather than to operate a browser runtime inside your Vapor image, ScreenshotNeo is a website screenshot API and MCP server. One GET request can return PNG, JPEG, WebP, or PDF output. It avoids packaging Puppeteer and Chrome into this application’s image; it does not replace Browsershot when you need the browser to run as part of your own application workflow.
The cURL example below saves a WebP capture. Get an API key first, replace the target URL as needed, and see the ScreenshotNeo documentation for request options.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo removes cookie/consent banners, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits cost nothing, and responses indicate the page verdict and billing status in headers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The Free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots.
Sign up for ScreenshotNeo’s free plan to get 1,000 screenshots a month with no card.
Frequently asked questions
Can Browsershot render HTML that is not loaded from a public webpage?
Yes. Browsershot supports rendering supplied HTML as well as webpages, according to Spatie’s introduction. The Node, Puppeteer, and browser runtime still need to be available for rendering.
Does choosing Vapor Docker mean Chrome must run in the same image?
No. An in-image browser is one implementation path. Sidecar Browsershot is also documented as a Lambda option; evaluate it against your deployment architecture and operational needs.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
