From 80cba50e420dd123f2f130b81363e6b527b7ead3 Mon Sep 17 00:00:00 2001 From: Alex Rudenko Date: Thu, 4 Aug 2022 10:18:00 +0200 Subject: [PATCH] docs: add documentation about Docker Closes #3072 --- README.md | 20 ++++++++++++++++++++ docker/README.md | 4 ++++ docs/index.md | 20 ++++++++++++++++++++ docs/troubleshooting.md | 1 + 4 files changed, 45 insertions(+) diff --git a/README.md b/README.md index f4beee07ed1cd..bd59222dccef9 100644 --- a/README.md +++ b/README.md @@ -198,6 +198,26 @@ See [`Page.evaluate`](https://pptr.dev/api/puppeteer.page.evaluate) and related +### Running in Docker + +Puppeteer offers a Docker image that includes Chromium along with the required dependencies and a pre-installed Puppeteer version. The image is available via the [GitHub Container Registry](https://github.com/puppeteer/puppeteer/pkgs/container/puppeteer). The latest image is tagged as `latest` and other tags match Puppeteer versions. For example, + +```sh +docker pull ghcr.io/puppeteer/puppeteer:latest # pulls the latest +docker pull ghcr.io/puppeteer/puppeteer:16.1.0 # pulls the image that contains Puppeteer v16.1.0 +``` + +The image is meant for running the browser in the sandobx mode and therefore, running the image requires the `SYS_ADMIN` capability. For example, + +```sh +docker run -i --init --cap-add=SYS_ADMIN --rm ghcr.io/puppeteer/puppeteer:latest node -e "`cat docker/test/smoke-test.js`" +``` + +Replace the path to [`smoke-test.js`](https://raw.githubusercontent.com/puppeteer/puppeteer/main/docker/test/smoke-test.js) with a path to your script. +The script can import or require the `puppeteer` module because it's pre-installed inside the image. + +Currently, the image includes the LTS version of Node.js. If you need to built an image based on a different base image, you can use our [`Dockerfile`](https://github.com/puppeteer/puppeteer/blob/main/docker/Dockerfile) as the starting point. + ### Working with Chrome Extensions Puppeteer can be used for testing Chrome Extensions. diff --git a/docker/README.md b/docker/README.md index d743e7edc9aa9..e90860bbd50d1 100644 --- a/docker/README.md +++ b/docker/README.md @@ -17,3 +17,7 @@ docker run -i --init --rm --cap-add=SYS_ADMIN --name puppeteer-chrome puppeteer- ``` `--cap-add=SYS_ADMIN` capability is needed to enable Chromium sandbox that makes the browser more secure. Alternatively, it should be possible to start the browser binary with the `--no-sandbox` flag. + +## GitHub Actions + +The image is automatically built, tested, and published by the [publish-docker.yml](https://github.com/puppeteer/puppeteer/blob/main/.github/workflows/publish-docker.yml) workflow. diff --git a/docs/index.md b/docs/index.md index 9a697d9d1fd53..c940dea4f5b13 100644 --- a/docs/index.md +++ b/docs/index.md @@ -204,6 +204,26 @@ See [`Page.evaluate`](https://pptr.dev/api/puppeteer.page.evaluate) and related +### Running in Docker + +Puppeteer offers a Docker image that includes Chromium along with the required dependencies and a pre-installed Puppeteer version. The image is available via the [GitHub Container Registry](https://github.com/puppeteer/puppeteer/pkgs/container/puppeteer). The latest image is tagged as `latest` and other tags match Puppeteer versions. For example, + +```sh +docker pull ghcr.io/puppeteer/puppeteer:latest # pulls the latest +docker pull ghcr.io/puppeteer/puppeteer:16.1.0 # pulls the image that contains Puppeteer v16.1.0 +``` + +The image is meant for running the browser in the sandobx mode and therefore, running the image requires the `SYS_ADMIN` capability. For example, + +```sh +docker run -i --init --cap-add=SYS_ADMIN --rm ghcr.io/puppeteer/puppeteer:latest node -e "`cat docker/test/smoke-test.js`" +``` + +Replace the path to [`smoke-test.js`](https://raw.githubusercontent.com/puppeteer/puppeteer/main/docker/test/smoke-test.js) with a path to your script. +The script can import or require the `puppeteer` module because it's pre-installed inside the image. + +Currently, the image includes the LTS version of Node.js. If you need to built an image based on a different base image, you can use our [`Dockerfile`](https://github.com/puppeteer/puppeteer/blob/main/docker/Dockerfile) as the starting point. + ### Working with Chrome Extensions Puppeteer can be used for testing Chrome Extensions. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index f5d4f818bf402..94106d3af569c 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -249,6 +249,7 @@ Running Puppeteer smoothly on CircleCI requires the following steps: ## Running Puppeteer in Docker > 👋 We used [Cirrus Ci](https://cirrus-ci.org/) to run our tests for Puppeteer in a Docker container until v3.0.x - see our historical [`Dockerfile.linux` (v3.0.1)](https://github.com/puppeteer/puppeteer/blob/v3.0.1/.ci/node12/Dockerfile.linux) for reference. +> Starting from v16.0.0 we are shipping a Docker image via the GitHub registry. The Dockerfile is located [here](https://github.com/puppeteer/puppeteer/blob/main/docker/Dockerfile) and the usage instructions are in the [README.md](https://github.com/puppeteer/puppeteer#running-in-docker). The instructions below might be still helpful if you are building your own image. Getting headless Chrome up and running in Docker can be tricky. The bundled Chromium that Puppeteer installs is missing the necessary