Extending the Docker Image

info

For hosted accounts, if you want to use a third-party module please get in touch!

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.

1. Create your own Dockerfile

   First, you'll want to write your own Dockerfile. In the example below, we're going to add the aws-sdk module.

   FROM registry.browserless.io/browserless/browserless/enterprise:latest
   
   # Install the AWS SDK
   RUN npm install aws-sdk

   Feel free to change the FROM value here. It's generally a good practice to "pin" this version to a value that won't change. For instance, if we want to use version 2.3.0 of Browserless Enterprise, we'd do:

   FROM registry.browserless.io/browserless/browserless/enterprise:2.3.0
   
   # Install the AWS SDK
   RUN npm install aws-sdk

   In either case, save your file and let's proceed.

2. Build the docker image

   Once the you have the file saved, it's as simple as building the image.

   docker build -t my/browserless:latest .

   Here, we're using a "dummy" user of my and a repo of browserless, tagging it as the latest. Feel free to change these however you see fit, especially if you want to push this built image into docker's public cloud or your own private image registry.

   It'll likely take a few minutes to pull all the dependencies locally and build, however subsequent builds will be much quicker since they'll have a local cache.

3. Run the image

   Now that you have a custom-built version you can apply all the same arguments to your start command (all environment variables and so on apply), you'll simply change the image you're running when you startup (note that we're whitelisting this new module, allowing browserless to execute it for security purposes).

   Here's an example of running the newly built image with the module whitelisted.

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

   Now your calls to /function and others will 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'\'',
     };
   };'

That's it! If you need to add more simply install your modules in the Dockerfile, build the image, and run it!