For AI agents: a documentation index is available at /llms.txt
Skip to main content

Extending the Docker Image

The Browserless Docker image includes Chrome/Chromium and common dependencies for browser automation. You'll need to extend the image when you require:

  • npm modules for use in /function API calls or custom scripts
  • System packages like fonts, libraries, or CLI tools
  • Custom configurations or startup scripts

This guide shows you how to build a custom image with your own dependencies.

Prerequisites
  • A Browserless Enterprise license
  • Docker installed on your infrastructure
info

For hosted accounts, contact us to use a third-party module.

  1. Create your own Dockerfile

    Create a Dockerfile. This example adds the aws-sdk module.

    FROM registry.browserless.io/browserless/browserless/enterprise:latest

    # Install the AWS SDK
    RUN npm install aws-sdk

    Pin the FROM value to a specific version for stability. For example, to use version 2.3.0:

    FROM registry.browserless.io/browserless/browserless/enterprise:2.3.0

    # Install the AWS SDK
    RUN npm install aws-sdk

    Save your file and proceed to the build step.

  2. Build the docker image

    Build the image with Docker:

    docker build -t my/browserless:latest .

    This tags the image as my/browserless:latest. Change the name and tag if you plan to push the image to a public or private registry.

    The first build takes a few minutes to pull dependencies. Subsequent builds are faster due to the local cache.

  3. Run the image

    Run the custom image with the same environment variables as the base image. Whitelist the new module with FUNCTION_EXTERNALS so Browserless can execute it.

    docker run -p 3000:3000 -e FUNCTION_EXTERNALS='["aws-sdk"]' my/browserless:latest

    Calls to /function now have access to the aws-sdk module:

    curl -X POST \
      http://localhost:3000/function \
      -H 'Content-Type: application/javascript' \
      -d 'const aws = require('\''aws-sdk'\'');

    module.exports = async () => {
      const data = Object.keys(aws);

      return {
        data,
        type: '\''text/plain'\'',
      };
    };'

To add more modules, install them in the Dockerfile, rebuild the image, and run it.

For a full list of environment variables you can pass at runtime, see the Docker configuration reference. To add custom HTTP or WebSocket routes to your image, see custom routes.

FAQ & Troubleshooting​

How do I get an Enterprise license?

Contact sales@browserless.io or visit the pricing page for Enterprise plan details.

Can I run Browserless on my own infrastructure?

Yes. Enterprise customers can self-host using the Docker image. See Docker deployment for setup instructions.

Next steps​

Docker deployment

self-host Browserless with Docker

Launch parameters

configure your Enterprise deployment