Available registries

Following the changes with the Rate Limiting on Docker Hub. Tweet here for more information in ����

• On the Docker Hub without any prefix: zenika/alpine-chrome
• On Google Cloud - available in the closest region:
  • Global: gcr.io/zenika-hub/alpine-chrome
  • Europe: eu.gcr.io/zenika-hub/alpine-chrome
  • Asia: asia.gcr.io/zenika-hub/alpine-chrome
  • US: us.gcr.io/zenika-hub/alpine-chrome

Supported tags and respective Dockerfile links

• latest, 89 (Dockerfile)
• with-node, 89-with-node, 89-with-node-14 (Dockerfile)
• with-puppeteer, 89-with-puppeteer (Dockerfile)
• with-playwright, 89-with-playwright (Dockerfile)
• with-selenoid, 89-with-selenoid (Dockerfile)
• with-chromedriver, 89-with-chromedriver (Dockerfile)
• 86, 85, 84, 83, 81, 80, 77, 76, 73, 72, 71, 68, 64
• 86-with-node, 85-with-node, 84-with-node, 83-with-node, 81-with-node, 80-with-node, 77-with-node, 76-with-node
• 86-with-puppeteer, 85-with-puppeteer,84-with-puppeteer, 83-with-puppeteer, 81-with-puppeteer, 80-with-puppeteer, 77-with-puppeteer, 76-with-puppeteer

alpine-chrome

Chrome running in headless mode in a tiny Alpine image

�� Why use a Headless Chrome

In the world of webdev, the ability to run quickly end-to-end tests are important. Popular technologies like Puppeteer enable developers to make fun things like testing, automating forms, crawling, generating screenshots, capturing timeline... And there is a secret: some of these features are directly available on Chrome! ��

�� Crafting the perfect container

• �� Tiniest Headless Chrome (Compressed size: 162.62MB)
• �� Easy to use, ephemeral and reproducible Headless Chrome with Docker
• �� Doc-friendly with examples for printing the DOM, generating an image with a mobile ratio or generating a PDF.
• ��‍♂️ Autobuild with the Docker Hub to sync the project and ship the images with confidence
• �� Up-to-date latest Chromium and tags available to test different versions of Chromium
• �� Secure with the best way to use Chrome and Docker - See "3 ways to securely use Chrome Headless" section
• �� Ready for internationalisation use: support for asian characters - See "screenshot-asia.js" file
• �� Ready for design use: support for WebGL, support for emojis- See "How to use with WebGL" section and "Emojis are not rendered properly" section
• �� Open Source with an Apache2 licence
• �� Community-built with external contributors - See " ✨ Contributors" section
• �� Dev-friendly with examples using NodeJS, Puppeteer, docker-compose and also a test with a X11 display - See "Run examples" section

3 ways to securely use Chrome Headless with this image

❌ With nothing

Launching the container using only docker container run -it zenika/alpine-chrome ... will fail with some logs similar to #33.

Please use the 3 others ways to use Chrome Headless.

✅ With --no-sandbox

Launch the container using:

docker container run -it --rm zenika/alpine-chrome and use the --no-sandbox flag for all your commands.

Be careful to know the website you're calling.

Explanation for the no-sandbox flag in a quick introduction here and for More in depth design document here

✅ With SYS_ADMIN capability

Launch the container using:docker container run -it --rm --cap-add=SYS_ADMIN zenika/alpine-chrome

This allows to run Chrome with sandboxing but needs unnecessary privileges from a Docker point of view.

✅ The best: With seccomp

Thanks to ever-awesome Jessie Frazelle seccomp profile for Chrome. This is The most secure way to run this Headless Chrome docker image.

chrome.json

Also available here wget https://raw.githubusercontent.com/jfrazelle/dotfiles/master/etc/docker/seccomp/chrome.json

Launch the container using:docker container run -it --rm --security-opt seccomp=$(pwd)/chrome.json zenika/alpine-chrome

How to use in command line

Default entrypoint

The default entrypoint does the following command: chromium-browser --headless --disable-gpu --disable-software-rasterizer --disable-dev-shm-usage

You can get full control by overriding the entrypoint using: docker container run -it --rm --entrypoint "" zenika/alpine-chrome chromium-browser ...

Use the devtools

Command (with no-sandbox): docker container run -d -p 9222:9222 zenika/alpine-chrome --no-sandbox --remote-debugging-address=0.0.0.0 --remote-debugging-port=9222 https://www.chromestatus.com/

Open your browser to: http://localhost:9222 and then click on the tab you want to inspect. Replace the beginninghttps://chrome-devtools-frontend.appspot.com/serve_file/@.../inspector.html?ws=localhost:9222/[END]bychrome-devtools://devtools/bundled/inspector.html?ws=localhost:9222/[END]

Print the DOM

Command (with no-sandbox): docker container run -it --rm zenika/alpine-chrome --no-sandbox --dump-dom https://www.chromestatus.com/

Print a PDF

Command (with no-sandbox): docker container run -it --rm -v $(pwd):/usr/src/app zenika/alpine-chrome --no-sandbox --print-to-pdf --hide-scrollbars https://www.chromestatus.com/

Take a screenshot

Command (with no-sandbox): docker container run -it --rm -v $(pwd):/usr/src/app zenika/alpine-chrome --no-sandbox --screenshot --hide-scrollbars https://www.chromestatus.com/

Size of a standard letterhead.

Command (with no-sandbox): docker container run -it --rm -v $(pwd):/usr/src/app zenika/alpine-chrome --no-sandbox --screenshot --hide-scrollbars --window-size=1280,1696 https://www.chromestatus.com/

Nexus 5x

Command (with no-sandbox): docker container run -it --rm -v $(pwd):/usr/src/app zenika/alpine-chrome --no-sandbox --screenshot --hide-scrollbars --window-size=412,732 https://www.chromestatus.com/

Screenshot owned by current user (by default the file is owned by the container user)

Command (with no-sandbox): docker container run -u `id -u $USER` -it --rm -v $(pwd):/usr/src/app zenika/alpine-chrome --no-sandbox --screenshot --hide-scrollbars --window-size=412,732 https://www.chromestatus.com/

How to use with Deno

Go the deno src folder. Build your image using this command:

docker image build -t zenika/alpine-chrome:with-deno-sample .

Then launch the container:

docker container run -it --rm zenika/alpine-chrome:with-deno-sample
 Download https://deno.land/std/examples/welcome.ts
 Warning Implicitly using master branch https://deno.land/std/examples/welcome.ts
 Compile https://deno.land/std/examples/welcome.ts
 Welcome to Deno ��

With your own file, use this command:

docker container run -it --rm -v $(pwd):/usr/src/app zenika/alpine-chrome:with-deno-sample run helloworld.ts
Compile file:///usr/src/app/helloworld.ts
Download https://deno.land/std/fmt/colors.ts
Warning Implicitly using master branch https://deno.land/std/fmt/colors.ts
Hello world!

How to use with Puppeteer

With tool like "Puppeteer", we can add a lot things with our Chrome Headless.

With some code in NodeJS, we can improve and make some tests.

See the "with-puppeteer" folder for more details. We have to follow the mapping of Chromium => Puppeteer described here.

If you have a NodeJS/Puppeteer script in your src folder named pdf.js, you can launch it using the following command:

docker container run -it --rm -v $(pwd)/src:/usr/src/app/src --cap-add=SYS_ADMIN zenika/alpine-chrome:with-puppeteer node src/pdf.js

With the "wqy-zenhei" library, you could also manipulate asian pages like in "screenshot-asia.js"

docker container run -it --rm -v $(pwd)/src:/usr/src/app/src --cap-add=SYS_ADMIN zenika/alpine-chrome:with-puppeteer node src/screenshot-asia.js

These websites are tested with the following supported languages:

• Chinese (with https://m.baidu.com)
• Japanese (with https://www.yahoo.co.jp/)
• Korean (with https://www.naver.com/)

How to use with Playwright

Like "Puppeteer", we can do a lot things using "Playwright" with our Chrome Headless.

Go to the with-playwright folder and launch the following command:

docker container run -it --rm -v $(pwd)/src:/usr/src/app/src --cap-add=SYS_ADMIN zenika/alpine-chrome:with-playwright node src/useragent.js

A example-chromium.png file will be created in your with-playwright/src folder.

How to use with WebGL

By default, this image works with WebGL.

If you want to disable it, make sure to add --disable-gpu when launching Chromium.

The with-webgl tag still exists but is deprecated. It will be removed before end of August 2020.

docker container run -it --rm --cap-add=SYS_ADMIN -v $(pwd):/usr/src/app zenika/alpine-chrome --screenshot --hide-scrollbars https://webglfundamentals.org/webgl/webgl-fundamentals.html

docker container run -it --rm --cap-add=SYS_ADMIN -v $(pwd):/usr/src/app zenika/alpine-chrome --screenshot --hide-scrollbars https://browserleaks.com/webgl

Links:

• https://github.com/adieuadieu/serverless-chrome/issues/108
• https://github.com/DevExpress/testcafe/issues/2116
• 'use-gl' values here

How to use with Chromedriver

ChromeDriver is a separate executable that Selenium WebDriver uses to control Chrome.You can use this image as a base for your Docker based selenium tests. See Guide for running Selenium tests using Chromedriver.

How to use with Selenoid

Selenoid is a powerful implementation of Selenium hub using Docker containers to launch browsers.Even if it used to run browsers in docker containers, it can be quite useful as lightweight Selenium replacement.with-selenoid image is a self sufficient selenium server, chrome and chromedriver installed.

You can run it with following command:

docker container run -it --rm --cap-add=SYS_ADMIN  -p 4444:4444 zenika/alpine-chrome:with-selenoid -capture-driver-logs

And run your tests against http://localhost:4444/wd/hub

One of the use-cases might be running automation tests in the environment with restricted Docker environmentlike on some CI systems like GitLab CI, etc. In such case you may not have permissions for --cap-add=SYS_ADMINand you will need to pass the --no-sandbox to chromedriver.

See more selenoid docs

Run as root and override default entrypoint

We can run the container as root with this command:

docker container run --rm -it --entrypoint "" --user root zenika/alpine-chrome sh

Run examples

Some examples are available on the examples directory:

• �� docker-compose to launch a chrome calling a nginx server in the same docker-compose
• ☸️ kubernetes to launch a pod with a headless chrome
• �� x11 to experiment this image with a X11 server.

References

• Headless Chrome website: https://developers.google.com/web/updates/2017/04/headless-chrome

• List of all options of the "Chromium" command line: https://peter.sh/experiments/chromium-command-line-switches/

• Where to file issues: https://github.com/Zenika/alpine-chrome/issues

• Maintained by: https://www.zenika.com

Versions (in latest)

Alpine version

docker container run -it --rm --entrypoint "" zenika/alpine-chrome cat /etc/alpine-release
3.13.2

Chrome version

docker container run -it --rm --entrypoint "" zenika/alpine-chrome chromium-browser --version
Chromium 89.0.4389.72

Image disk size

docker image inspect zenika/alpine-chrome --format='{{.Size}}'
412889529

✨ Contributors

Thanks goes to these wonderful people (emoji key):

Julien Landuré �� �� ⚠️ �� �� ��	Yonggang Luo �� �� ��	Dennis Koch �� �� ��	Sargon Piraev ��	Eric Briand ��	栩风 �� ��	Roman Pushkin ��
Juan Lladó ��	Chris Watson ��	Wang Guan ��	Óscar Soto Sánchez ��	Calinoiu Alexandru Nicolae ��	Mark Macdonald ��	Felix Mann ��
horacimacias ��	Emil Kjer ��	Jeff Gonzalez ��	George Gaál ��	wheestermans31 ��	Hodossy, Szabolcs ��	Corentin Ardeois ��
Danny Althoff ��	Chad Wilson �� ��	fenchu ��	nrawat151290 ��	x0rzkov �� ��	Jakob Ketterl ��	Piotr Sikora �� ��
Pierre Grimaud ��	Niek van der Maas �� ��	llange �� ��	Ageng D. Prastyawan ��	Neel Kamath ��	Peter Dave Hello ��	Taras �� ��
Antoine Oili ��	Manuel Cepeda ��	Simon Frey ��	Santhosh C ��

This project follows the all-contributors specification. Contributions of any kind welcome!

�� Show your support

⭐️ this repo or leave a comment here

�� Support this repository using GitHub Sponsor