The browserless docker container is highly-configurable, and accepts parameters through environment variables when starting. You can set parameters such as port, connection-timeout, queueing and more. Below is a description of each parameter, what they mean, and what they default to.

Chrome information

Browserless automatically builds labels with each release regarding important information like the current browser version, the version of puppeteer that's supported, and even the debugger version protocol. You can access this information by running the command below:

$ docker inspect browserless/chrome

Port

By default browserless listens on port 3000. You can configure this in docker by using it's port mapping functionality. As an example, let's say you want to have it listen port 8080, you would run it like so:

Max Concurrent Sessions

Since running Chrome can be rather resource intensive you'll probably want to limit the number of concurrent sessions. This is, by default, set to 5 when not specified. Once the limit is reached then queueing begins to take place and requests will wait until more workers are ready.

It's best to keep this limit small and grow it over time as it's easy to starve resources when running on restricted hardware.

Connection Timeout

Connection timeout is a parameter that sets how long any session can run for. This is in place to prevent scripts that don't cleanup properly, or run into errors tha cause them to hang. The value of which can be set in milliseconds, and defaults to 30000, or 30 seconds.

To allow more time for sessions, simply change it by setting CONNECTION_TIMEOUT when running.

Max Queue Length

This value determines how many items in the queue are allowed before requests are issued a 429 response code and closed. This mechanism is in place to prevent consumers from accidentally (or purposefully) triggering a denial-of-service. By default the image only allows a queue of 5 requests before beginning to fail more. As an example, if you have a MAX_CONCURRENT_SESSIONS of 5 and a MAX_QUEUE_LENGTH of 5, then 10 concurrent connections are allowed (5 running then 5 pending).

Pre-booting Chrome

You can, optionally, pre-boot Chrome and keep it in a pool of instances (determined by MAX_CONCURRENT_SESSIONS) in order to cut-down on the boot time. To enable this, run your docker command as you normally would plus the PREBOOT_CHROME=true flag.

Securing your instance

If you're exposing your instance to the world, but don't want anyone to use it, you can optionally apply a TOKEN param that will restrict calls without a token query-string parameter. When present, browserless will reject any calls that don't have a matching token.

Enable XVFB

By default browserless will take care of XVFB running automatically, which essentially means this is defaulted to true. However, in some hosting environments it's not possible to write to the appropriate folders to support XVFB and you should set this parameter to false.

The screencast API depends on this setting to be true and will fail when turned off.

Exit on health failure

browserless routinely checks on the health of the image as it's running. Sometimes it's helpful to have it restart automatically when CPU or Memory usage are above 100% for a period of time (by default 5 minutes). In order for browserless to restart on health-failure checks, you'll have to set a parameter of EXIT_ON_HEALTH_FAILURE=true.

Persisting Metrics

browserless captures metrics while it's running, and exposes them via the /metrics endpoint. These, by default, don't persist anywhere unless you tell browserless where to persist them. When provided, the docker image will also attempt to read the metrics on startup and write to it periodically during execution.

In this run command we're mounting the machines /root path so that the docker can access it at /root, be sure to change this to fit your use-case.

Exposing built-in modules to /function

The /function endpoint allows for user-submitted code to be ran inside the docker-image without the need for another compilation step. By default functions are not allowed to require modules (both built-in's or externally). To enable Node's built-in modules you'll need to supply an array of modules available.

Exposing external modules to /function

The /function endpoint allows for user-submitted code to be ran inside the docker-image without the need for another compilation step. By default functions are not allowed to require modules (both built-in's or externally). To enable external modules you'll need to supply an array of modules available.

Here we're allowing both the request and fetch modules to be required in the /function endpoint.

Keeping Chrome Alive

When the PREBOOT_CHROME flag is set, you can optionally keep Chrome "alive" after sessions are complete. This allows you to re-use Chrome instances without having to start and stop them (making for much faster execution). To enable this behavior, set the PREBOOT_CHROME=true and KEEP_ALIVE=true.

Browserless will close Chrome after 30 minutes to try and mitigate issues with Chrome consuming too many resources. This is configurable as well with the CHROME_REFRESH_TIME flag.

When using KEEP_ALIVE Chrome will retain information about prior-sessions such as cookies and login contexts. You'll also need to replace browser.close() with browser.disconnect() in your puppeteer code.

Chrome Refresh Time

When both PREBOOT_CHROME and KEEP_ALIVE are true browserless keeps track of how long Chrome has been running, and will attempt to close it after a certain period. By default it will try and restart Chrome after 30 minutes. You can configure this behavior with the CHROME_REFRESH_TIME flag.

The CHROME_REFRESH_TIME flag accepts a value in milliseconds to keep Chrome running before it attempts to close it. Below we set this threshold to one hour.