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
- Global:
Dockerfile
links
Supported tags and respective 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.
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 beginning
https://chrome-devtools-frontend.appspot.com/serve_file/@.../inspector.html?ws=localhost:9222/[END]
by
chrome-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:
- adieuadieu/serverless-chrome#108
- DevExpress/testcafe#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 environment
like on some CI systems like GitLab CI, etc. In such case you may not have permissions for --cap-add=SYS_ADMIN
and 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):
This project follows the all-contributors specification. Contributions of any kind welcome!