About headless-shell

The headless-shell project provides a Docker image,chromedp/headless-shell, containing a pre-builtversion of Chrome's headless-shell -- a slimmed down version of Chrome thatis useful for driving, profiling, or testing web pages.

Notably, this Docker image has been created expressly for the Go chromedppackage, which provides a simple and easy to use API for drivingbrowsers compatible with the Chrome Debugging Protocol.

The version of headless-shell contained in this Docker image has beenmodified from the original Chromium source tree, to report the same user agentas Chrome, and has had other minor modifications made to it in order make itbetter suited for use in an embedded context.

Running

You can use this Docker image in the usual way:

# pull latest version of headless-shell
$ docker pull chromedp/headless-shell:latest

# pull specific tagged version of headless-shell
$ docker pull chromedp/headless-shell:74.0.3717.1

# run
$ docker run -d -p 9222:9222 --rm --name headless-shell chromedp/headless-shell

# if headless-shell is crashing with a BUS_ADRERR error, pass a larger shm-size:
$ docker run -d -p 9222:9222 --rm --name headless-shell --shm-size 2G chromedp/headless-shell

# run as unprivileged user
# get seccomp profile from https://raw.githubusercontent.com/jfrazelle/dotfiles/master/etc/docker/seccomp/chrome.json
$ docker run -d -p 9222:9222 --user nobody --security-opt seccomp=chrome.json --entrypoint '/headless-shell/headless-shell' chromedp/headless-shell --remote-debugging-address=0.0.0.0 --remote-debugging-port=9222 --disable-gpu --headless

Using as a base image

When using chromedp/headless-shell as a base image to build an image that runs your own program, You could experience zombie process problem. To reap zombie processeses, use dumb-init or tini on your Dockerfile's ENTRYPOINT

FROM chromedp/headless-shell:latest
...
# Install dumb-init or tini
RUN apt install dumb-init
# or RUN apt install tini
...
ENTRYPOINT ["dumb-init", "--"]
# or ENTRYPOINT ["tini", "--"]
CMD ["/path/to/your/program"]

If running Docker 1.13.0 or later, use docker run's --init arg instead to reap zombie processes.

docker run -d -p <PORT>:<PORT> --name <your-program> --init <your-image>

Building and Packaging

The following contains instructions for building and packaging thechromedp/headless-shell Docker image manually.

Setup and Building

If you'd like to build this image yourself, locally, you will need to buildheadless-shell manually from the Chromium source. As such you will need tosetup Chromium's depot_tools, your build environment, and a full checkout ofthe Chromium source tree and its related dependencies.

Please see the following for instructions on building Chromium andheadless-shell on Linux:

• Checking out and building Chromium on Linux
• Building Headless Chromium

Before proceeding, please ensure you have fully completed the above, havemanually built headless-shell at least once, and that your Chromium sourcetree is up-to-date.

Building

After you are able to successfully build headless-shell directly from theChromium source tree, you can simply run build-docker.sh:

# build headless-shell
$ ./build-headless-shell.sh /path/to/chromium/src 74.0.3717.1

# build docker image (uses $PWD/out/headless-shell-$VER.tar.bz2)
$ ./build-docker.sh 74.0.3717.1