Browserless Docs

Having issues with docker? Email us

The browserless docker container 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:

$ docker run --cap-add SYS_ADMIN -p 8080:3000 --restart always -d --name browserless browserless/chrome

This should allow you some flexibility in how to run the image.

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.

To set this to a different number, say 10, issue your run like so:

$ docker run -e "MAX_CONCURRENT_SESSIONS=10" --cap-add SYS_ADMIN -p 3000:3000 --restart always -d --name browserless browserless/chrome

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.

$ docker run -e "CONNECTION_TIMEOUT=60000" --cap-add SYS_ADMIN -p 3000:3000 --restart always -d --name browserless browserless/chrome

Debug Timeout

Debug sessions are treated independently of typical sessions as they likely last longer and are slower due to the amount of interaction and overhead. For this reason, you can optionally set debug sessions to a higher limit via the DEBUG_CONNECTION_TIMEOUT variable. This value is in milliseconds, and defaults to 300000 or 5 minutes.

The script below adjust this to 10 minutes.

$ docker run -e "DEBUG_CONNECTION_TIMEOUT=600000" --cap-add SYS_ADMIN -p 3000:3000 --restart always -d --name browserless browserless/chrome

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).

To adjust this value, simply set it via MAX_QUEUE_LENGTH.

$ docker run -e "MAX_QUEUE_LENGTH=10" --cap-add SYS_ADMIN -p 3000:3000 --restart always -d --name browserless browserless/chrome

Log Activity

This boolean flag tells the browserless image if it should log activity every 5 seconds. This is useful if you’re trying to test loads and how work is being effectively consumed. If you wish to turn this off, set it to false

$ docker run -e "LOG_ACTIVITY=false" --cap-add SYS_ADMIN -p 3000:3000 --restart always -d --name browserless browserless/chrome