mirror of
https://github.com/puppeteer/puppeteer
synced 2024-06-14 14:02:48 +00:00
chore: update troubleshooting guide (#9123)
This PR updates the troubleshooting guide with some information regarding the new `exports` resolution and cache directory. This PR also reformats some of the other MD documents.
This commit is contained in:
jrandolf
GitHub
@@ -4,12 +4,39 @@ sidebar_position: 3
|
||||
|
||||
# Troubleshooting
|
||||
|
||||
## `Cannot find module 'puppeteer-core/internal/...'`
|
||||
|
||||
This can occur is your Node.js version is lower than 14 or you are using a
|
||||
custom resolver (such as
|
||||
[`jest-resolve`](https://www.npmjs.com/package/jest-resolve)). For the former,
|
||||
we do not support deprecated versions of Node.js. For the latter, usually
|
||||
upgrading the resolver (or its parent module such as `jest`) will work (e.g.
|
||||
https://github.com/puppeteer/puppeteer/issues/9121)
|
||||
|
||||
## `Could not find expected browser locally`
|
||||
|
||||
Starting from v19.0.0, Puppeteer will download browsers into
|
||||
`~/.cache/puppeteer` using
|
||||
[`os.homedir`](https://nodejs.org/api/os.html#oshomedir) for better caching
|
||||
between Puppeteer upgrades. Generally the home directory is well-defined (even
|
||||
on Windows), but occasionally the home directory may not be available. In this
|
||||
case, we provide the `PUPPETEER_CACHE_DIR` variable which allows you to change
|
||||
the installation directory.
|
||||
|
||||
For example,
|
||||
|
||||
```sh
|
||||
PUPPETEER_CACHE_DIR=$(pwd) npm install puppeteer
|
||||
PUPPETEER_CACHE_DIR=$(pwd) node <script-path>
|
||||
```
|
||||
|
||||
## Chrome headless doesn't launch on Windows
|
||||
|
||||
Some [chrome policies](https://support.google.com/chrome/a/answer/7532015) might enforce running Chrome/Chromium
|
||||
with certain extensions.
|
||||
Some [chrome policies](https://support.google.com/chrome/a/answer/7532015) might
|
||||
enforce running Chrome/Chromium with certain extensions.
|
||||
|
||||
Puppeteer passes `--disable-extensions` flag by default and will fail to launch when such policies are active.
|
||||
Puppeteer passes `--disable-extensions` flag by default and will fail to launch
|
||||
when such policies are active.
|
||||
|
||||
To work around this, try running without the flag:
|
||||
|
||||
@@ -19,12 +46,14 @@ const browser = await puppeteer.launch({
|
||||
});
|
||||
```
|
||||
|
||||
> Context: [issue 3681](https://github.com/puppeteer/puppeteer/issues/3681#issuecomment-447865342).
|
||||
> Context:
|
||||
> [issue 3681](https://github.com/puppeteer/puppeteer/issues/3681#issuecomment-447865342).
|
||||
|
||||
## Chrome headless doesn't launch on UNIX
|
||||
|
||||
Make sure all the necessary dependencies are installed. You can run `ldd chrome | grep not` on a Linux
|
||||
machine to check which dependencies are missing. The common ones are provided below.
|
||||
Make sure all the necessary dependencies are installed. You can run
|
||||
`ldd chrome | grep not` on a Linux machine to check which dependencies are
|
||||
missing. The common ones are provided below.
|
||||
|
||||
<details>
|
||||
<summary>Debian (e.g. Ubuntu) Dependencies</summary>
|
||||
@@ -97,7 +126,8 @@ xorg-x11-fonts-Type1
|
||||
xorg-x11-utils
|
||||
```
|
||||
|
||||
After installing dependencies you need to update nss library using this command
|
||||
After installing dependencies you need to update `nss` library using this
|
||||
command
|
||||
|
||||
```
|
||||
yum update nss -y
|
||||
@@ -108,15 +138,19 @@ yum update nss -y
|
||||
<details>
|
||||
<summary>Check out discussions</summary>
|
||||
|
||||
- [#290](https://github.com/puppeteer/puppeteer/issues/290) - Debian troubleshooting <br/>
|
||||
- [#391](https://github.com/puppeteer/puppeteer/issues/391) - CentOS troubleshooting <br/>
|
||||
- [#379](https://github.com/puppeteer/puppeteer/issues/379) - Alpine troubleshooting <br/>
|
||||
- [#290](https://github.com/puppeteer/puppeteer/issues/290) - Debian
|
||||
troubleshooting <br/>
|
||||
- [#391](https://github.com/puppeteer/puppeteer/issues/391) - CentOS
|
||||
troubleshooting <br/>
|
||||
- [#379](https://github.com/puppeteer/puppeteer/issues/379) - Alpine
|
||||
troubleshooting <br/>
|
||||
|
||||
</details>
|
||||
|
||||
## Chrome headless disables GPU compositing
|
||||
|
||||
Chrome/Chromium requires `--use-gl=egl` to [enable GPU acceleration in headless mode](https://github.com/chromium/chromium/commit/19671359ae25aa1e30bde90f8ff92453eeaac2ba).
|
||||
Chrome/Chromium requires `--use-gl=egl` to
|
||||
[enable GPU acceleration in headless mode](https://github.com/chromium/chromium/commit/19671359ae25aa1e30bde90f8ff92453eeaac2ba).
|
||||
|
||||
```ts
|
||||
const browser = await puppeteer.launch({
|
||||
@@ -134,16 +168,22 @@ If you get an error that looks like this when trying to launch Chromium:
|
||||
spawn /Users/.../node_modules/puppeteer/.local-chromium/mac-756035/chrome-mac/Chromium.app/Contents/MacOS/Chromium ENOENT
|
||||
```
|
||||
|
||||
This means that the browser was downloaded but failed to be extracted correctly. The most common cause is a bug in Node.js v14.0.0 which broke `extract-zip`, the module Puppeteer uses to extract browser downloads into the right place. The bug was fixed in Node.js v14.1.0, so please make sure you're running that version or higher.
|
||||
This means that the browser was downloaded but failed to be extracted correctly.
|
||||
The most common cause is a bug in Node.js v14.0.0 which broke `extract-zip`, the
|
||||
module Puppeteer uses to extract browser downloads into the right place. The bug
|
||||
was fixed in Node.js v14.1.0, so please make sure you're running that version or
|
||||
higher.
|
||||
|
||||
## Setting Up Chrome Linux Sandbox
|
||||
|
||||
In order to protect the host environment from untrusted web content, Chrome uses [multiple layers of sandboxing](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/linux/sandboxing.md). For this to work properly,
|
||||
the host should be configured first. If there's no good sandbox for Chrome to use, it will crash
|
||||
with the error `No usable sandbox!`.
|
||||
In order to protect the host environment from untrusted web content, Chrome uses
|
||||
[multiple layers of sandboxing](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/linux/sandboxing.md).
|
||||
For this to work properly, the host should be configured first. If there's no
|
||||
good sandbox for Chrome to use, it will crash with the error
|
||||
`No usable sandbox!`.
|
||||
|
||||
If you **absolutely trust** the content you open in Chrome, you can launch Chrome
|
||||
with the `--no-sandbox` argument:
|
||||
If you **absolutely trust** the content you open in Chrome, you can launch
|
||||
Chrome with the `--no-sandbox` argument:
|
||||
|
||||
```ts
|
||||
const browser = await puppeteer.launch({
|
||||
@@ -153,7 +193,8 @@ const browser = await puppeteer.launch({
|
||||
|
||||
:::caution
|
||||
|
||||
Running without a sandbox is **strongly discouraged**. Consider configuring a sandbox instead.
|
||||
Running without a sandbox is **strongly discouraged**. Consider configuring a
|
||||
sandbox instead.
|
||||
|
||||
:::
|
||||
|
||||
@@ -161,9 +202,10 @@ There are 2 ways to configure a sandbox in Chromium.
|
||||
|
||||
### [recommended] Enable [user namespace cloning](http://man7.org/linux/man-pages/man7/user_namespaces.7.html)
|
||||
|
||||
User namespace cloning is only supported by modern kernels. Unprivileged user namespaces are generally fine to enable,
|
||||
but in some cases they open up more kernel attack surface for (unsandboxed) non-root processes to elevate to
|
||||
kernel privileges.
|
||||
User namespace cloning is only supported by modern kernels. Unprivileged user
|
||||
namespaces are generally fine to enable, but in some cases they open up more
|
||||
kernel attack surface for (unsandboxed) non-root processes to elevate to kernel
|
||||
privileges.
|
||||
|
||||
```bash
|
||||
sudo sysctl -w kernel.unprivileged_userns_clone=1
|
||||
@@ -171,9 +213,10 @@ sudo sysctl -w kernel.unprivileged_userns_clone=1
|
||||
|
||||
### [alternative] Setup [setuid sandbox](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/linux/suid_sandbox_development.md)
|
||||
|
||||
The setuid sandbox comes as a standalone executable and is located next to the Chromium that Puppeteer downloads. It is
|
||||
fine to re-use the same sandbox executable for different Chromium versions, so the following could be
|
||||
done only once per host environment:
|
||||
The setuid sandbox comes as a standalone executable and is located next to the
|
||||
Chromium that Puppeteer downloads. It is fine to re-use the same sandbox
|
||||
executable for different Chromium versions, so the following could be done only
|
||||
once per host environment:
|
||||
|
||||
```bash
|
||||
# cd to the downloaded instance
|
||||
@@ -186,8 +229,8 @@ sudo cp -p chrome_sandbox /usr/local/sbin/chrome-devel-sandbox
|
||||
export CHROME_DEVEL_SANDBOX=/usr/local/sbin/chrome-devel-sandbox
|
||||
```
|
||||
|
||||
You might want to export the `CHROME_DEVEL_SANDBOX` env variable by default. In this case, add the following to the `~/.bashrc`
|
||||
or `.zshenv`:
|
||||
You might want to export the `CHROME_DEVEL_SANDBOX` env variable by default. In
|
||||
this case, add the following to the `~/.bashrc` or `.zshenv`:
|
||||
|
||||
```bash
|
||||
export CHROME_DEVEL_SANDBOX=/usr/local/sbin/chrome-devel-sandbox
|
||||
@@ -195,11 +238,15 @@ export CHROME_DEVEL_SANDBOX=/usr/local/sbin/chrome-devel-sandbox
|
||||
|
||||
## Running Puppeteer on Travis CI
|
||||
|
||||
> 👋 We ran our tests for Puppeteer on Travis CI until v6.0.0 (when we've migrated to GitHub Actions) - see our historical [`.travis.yml` (v5.5.0)](https://github.com/puppeteer/puppeteer/blob/v5.5.0/.travis.yml) for reference.
|
||||
> 👋 We ran our tests for Puppeteer on Travis CI until v6.0.0 (when we've
|
||||
> migrated to GitHub Actions) - see our historical
|
||||
> [`.travis.yml` (v5.5.0)](https://github.com/puppeteer/puppeteer/blob/v5.5.0/.travis.yml)
|
||||
> for reference.
|
||||
|
||||
Tips-n-tricks:
|
||||
|
||||
- [xvfb](https://en.wikipedia.org/wiki/Xvfb) service should be launched in order to run Chromium in non-headless mode
|
||||
- [xvfb](https://en.wikipedia.org/wiki/Xvfb) service should be launched in order
|
||||
to run Chromium in non-headless mode
|
||||
- Runs on Xenial Linux on Travis by default
|
||||
- Runs `npm install` by default
|
||||
- `node_modules` is cached by default
|
||||
@@ -218,17 +265,17 @@ script:
|
||||
|
||||
Running Puppeteer smoothly on CircleCI requires the following steps:
|
||||
|
||||
1. Start with a [NodeJS
|
||||
image](https://circleci.com/docs/2.0/circleci-images/#nodejs) in your config
|
||||
like so:
|
||||
1. Start with a
|
||||
[NodeJS image](https://circleci.com/docs/2.0/circleci-images/#nodejs) in your
|
||||
config like so:
|
||||
```yaml
|
||||
docker:
|
||||
- image: circleci/node:14 # Use your desired version
|
||||
environment:
|
||||
NODE_ENV: development # Only needed if puppeteer is in `devDependencies`
|
||||
```
|
||||
1. Dependencies like `libXtst6` probably need to be installed via `apt-get`,
|
||||
so use the
|
||||
1. Dependencies like `libXtst6` probably need to be installed via `apt-get`, so
|
||||
use the
|
||||
[threetreeslight/puppeteer](https://circleci.com/orbs/registry/orb/threetreeslight/puppeteer)
|
||||
orb
|
||||
([instructions](https://circleci.com/orbs/registry/orb/threetreeslight/puppeteer#quick-start)),
|
||||
@@ -243,20 +290,27 @@ Running Puppeteer smoothly on CircleCI requires the following steps:
|
||||
at ChildProcess.spawn (internal/child_process.js:394:11)
|
||||
```
|
||||
This is likely caused by Jest autodetecting the number of processes on the
|
||||
entire machine (`36`) rather than the number allowed to your container
|
||||
(`2`). To fix this, set `jest --maxWorkers=2` in your test command.
|
||||
entire machine (`36`) rather than the number allowed to your container (`2`).
|
||||
To fix this, set `jest --maxWorkers=2` in your test command.
|
||||
|
||||
## 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.
|
||||
> 👋 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
|
||||
shared library dependencies.
|
||||
Getting headless Chrome up and running in Docker can be tricky. The bundled
|
||||
Chromium that Puppeteer installs is missing the necessary shared library
|
||||
dependencies.
|
||||
|
||||
To fix, you'll need to install the missing dependencies and the
|
||||
latest Chromium package in your Dockerfile:
|
||||
To fix, you'll need to install the missing dependencies and the latest Chromium
|
||||
package in your Dockerfile:
|
||||
|
||||
```Dockerfile
|
||||
FROM node:14-slim
|
||||
@@ -308,7 +362,8 @@ Build the container:
|
||||
docker build -t puppeteer-chrome-linux .
|
||||
```
|
||||
|
||||
Run the container by passing `node -e "<yourscript.js content as a string>"` as the command:
|
||||
Run the container by passing `node -e "<yourscript.js content as a string>"` as
|
||||
the command:
|
||||
|
||||
```bash
|
||||
docker run -i --init --rm --cap-add=SYS_ADMIN \
|
||||
@@ -316,12 +371,15 @@ Run the container by passing `node -e "<yourscript.js content as a string>"` as
|
||||
node -e "`cat yourscript.js`"
|
||||
```
|
||||
|
||||
There's a full example at https://github.com/ebidel/try-puppeteer that shows
|
||||
how to run this Dockerfile from a webserver running on App Engine Flex (Node).
|
||||
There's a full example at https://github.com/ebidel/try-puppeteer that shows how
|
||||
to run this Dockerfile from a webserver running on App Engine Flex (Node).
|
||||
|
||||
### Running on Alpine
|
||||
|
||||
The [newest Chromium package](https://pkgs.alpinelinux.org/package/edge/community/x86_64/chromium) supported on Alpine is 100, which corresponds to [Puppeteer v13.5.0](https://github.com/puppeteer/puppeteer/releases/tag/v13.5.0).
|
||||
The
|
||||
[newest Chromium package](https://pkgs.alpinelinux.org/package/edge/community/x86_64/chromium)
|
||||
supported on Alpine is 100, which corresponds to
|
||||
[Puppeteer v13.5.0](https://github.com/puppeteer/puppeteer/releases/tag/v13.5.0).
|
||||
|
||||
Example Dockerfile:
|
||||
|
||||
@@ -362,7 +420,8 @@ USER pptruser
|
||||
|
||||
## Running Puppeteer on GitlabCI
|
||||
|
||||
This is very similar to some of the instructions above, but require a bit different configuration to finally achieve success.
|
||||
This is very similar to some of the instructions above, but require a bit
|
||||
different configuration to finally achieve success.
|
||||
|
||||
Usually the issue looks like this:
|
||||
|
||||
@@ -375,23 +434,34 @@ You need to patch two places:
|
||||
1. Your `gitlab-ci.yml` config
|
||||
2. Arguments' list when launching pupepeteer
|
||||
|
||||
In `gitlab-ci.yml` we need to install some packages to make it possible to launch headless Chrome in your docker env:
|
||||
In `gitlab-ci.yml` we need to install some packages to make it possible to
|
||||
launch headless Chrome in your docker env:
|
||||
|
||||
```yml
|
||||
before_script:
|
||||
- apt-get update
|
||||
- apt-get install -yq gconf-service libasound2 libatk1.0-0 libc6 libcairo2 libcups2 libdbus-1-3 libexpat1 libfontconfig1 libgcc1 libgconf-2-4 libgdk-pixbuf2.0-0 libglib2.0-0 libgtk-3-0 libnspr4 libpango-1.0-0 libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6 ca-certificates fonts-liberation libnss3 lsb-release xdg-utils wget
|
||||
- apt-get install -yq gconf-service libasound2 libatk1.0-0 libc6 libcairo2
|
||||
libcups2 libdbus-1-3 libexpat1 libfontconfig1 libgcc1 libgconf-2-4
|
||||
libgdk-pixbuf2.0-0 libglib2.0-0 libgtk-3-0 libnspr4 libpango-1.0-0
|
||||
libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcomposite1
|
||||
libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1
|
||||
libxss1 libxtst6 ca-certificates fonts-liberation libnss3 lsb-release
|
||||
xdg-utils wget
|
||||
```
|
||||
|
||||
Next, you have to use `'--no-sandbox'` mode and also `'--disable-setuid-sandbox'` when launching Puppeteer. This can be done by passing them as an arguments to your `.launch()` call: `puppeteer.launch({ args: ['--no-sandbox', '--disable-setuid-sandbox'] });`.
|
||||
Next, you have to use `'--no-sandbox'` mode and also
|
||||
`'--disable-setuid-sandbox'` when launching Puppeteer. This can be done by
|
||||
passing them as an arguments to your `.launch()` call:
|
||||
`puppeteer.launch({ args: ['--no-sandbox', '--disable-setuid-sandbox'] });`.
|
||||
|
||||
#### Tips
|
||||
|
||||
By default, Docker runs a container with a `/dev/shm` shared memory space 64MB.
|
||||
This is [typically too small](https://github.com/c0b/chrome-in-docker/issues/1) for Chrome
|
||||
and will cause Chrome to crash when rendering large pages. To fix, run the container with
|
||||
`docker run --shm-size=1gb` to increase the size of `/dev/shm`. Since Chrome 65, this is no
|
||||
longer necessary. Instead, launch the browser with the `--disable-dev-shm-usage` flag:
|
||||
This is [typically too small](https://github.com/c0b/chrome-in-docker/issues/1)
|
||||
for Chrome and will cause Chrome to crash when rendering large pages. To fix,
|
||||
run the container with `docker run --shm-size=1gb` to increase the size of
|
||||
`/dev/shm`. Since Chrome 65, this is no longer necessary. Instead, launch the
|
||||
browser with the `--disable-dev-shm-usage` flag:
|
||||
|
||||
```ts
|
||||
const browser = await puppeteer.launch({
|
||||
@@ -399,11 +469,14 @@ const browser = await puppeteer.launch({
|
||||
});
|
||||
```
|
||||
|
||||
This will write shared memory files into `/tmp` instead of `/dev/shm`. See [crbug.com/736452](https://bugs.chromium.org/p/chromium/issues/detail?id=736452) for more details.
|
||||
This will write shared memory files into `/tmp` instead of `/dev/shm`. See
|
||||
[crbug.com/736452](https://bugs.chromium.org/p/chromium/issues/detail?id=736452)
|
||||
for more details.
|
||||
|
||||
Seeing other weird errors when launching Chrome? Try running your container
|
||||
with `docker run --cap-add=SYS_ADMIN` when developing locally. Since the Dockerfile
|
||||
adds a `pptr` user as a non-privileged user, it may not have all the necessary privileges.
|
||||
Seeing other weird errors when launching Chrome? Try running your container with
|
||||
`docker run --cap-add=SYS_ADMIN` when developing locally. Since the Dockerfile
|
||||
adds a `pptr` user as a non-privileged user, it may not have all the necessary
|
||||
privileges.
|
||||
|
||||
[dumb-init](https://github.com/Yelp/dumb-init) is worth checking out if you're
|
||||
experiencing a lot of zombies Chrome processes sticking around. There's special
|
||||
@@ -414,46 +487,80 @@ properly in some cases (e.g. in Docker).
|
||||
|
||||
### Running Puppeteer on Google App Engine
|
||||
|
||||
The Node.js runtime of the [App Engine standard environment](https://cloud.google.com/appengine/docs/standard/nodejs/) comes with all system packages needed to run Headless Chrome.
|
||||
The Node.js runtime of the
|
||||
[App Engine standard environment](https://cloud.google.com/appengine/docs/standard/nodejs/)
|
||||
comes with all system packages needed to run Headless Chrome.
|
||||
|
||||
To use `puppeteer`, simply list the module as a dependency in your `package.json` and deploy to Google App Engine. Read more about using `puppeteer` on App Engine by following [the official tutorial](https://cloud.google.com/appengine/docs/standard/nodejs/using-headless-chrome-with-puppeteer).
|
||||
To use `puppeteer`, simply list the module as a dependency in your
|
||||
`package.json` and deploy to Google App Engine. Read more about using
|
||||
`puppeteer` on App Engine by following
|
||||
[the official tutorial](https://cloud.google.com/appengine/docs/standard/nodejs/using-headless-chrome-with-puppeteer).
|
||||
|
||||
### Running Puppeteer on Google Cloud Functions
|
||||
|
||||
The Node.js 10 runtime of [Google Cloud Functions](https://cloud.google.com/functions/docs/) comes with all system packages needed to run Headless Chrome.
|
||||
The Node.js 10 runtime of
|
||||
[Google Cloud Functions](https://cloud.google.com/functions/docs/) comes with
|
||||
all system packages needed to run Headless Chrome.
|
||||
|
||||
To use `puppeteer`, simply list the module as a dependency in your `package.json` and deploy your function to Google Cloud Functions using the `nodejs10` runtime.
|
||||
To use `puppeteer`, simply list the module as a dependency in your
|
||||
`package.json` and deploy your function to Google Cloud Functions using the
|
||||
`nodejs10` runtime.
|
||||
|
||||
### Running Puppeteer on Google Cloud Run
|
||||
|
||||
The default Node.js runtime of [Google Cloud Run](https://cloud.google.com/run/docs/) does not come with the system packages needed to run Headless Chrome. You will need to set up your own `Dockerfile` and [include the missing dependencies](#chrome-headless-doesnt-launch-on-unix).
|
||||
The default Node.js runtime of
|
||||
[Google Cloud Run](https://cloud.google.com/run/docs/) does not come with the
|
||||
system packages needed to run Headless Chrome. You will need to set up your own
|
||||
`Dockerfile` and
|
||||
[include the missing dependencies](#chrome-headless-doesnt-launch-on-unix).
|
||||
|
||||
### Running Puppeteer on Heroku
|
||||
|
||||
Running Puppeteer on Heroku requires some additional dependencies that aren't included on the Linux box that Heroku spins up for you. To add the dependencies on deploy, add the Puppeteer Heroku buildpack to the list of buildpacks for your app under Settings > Buildpacks.
|
||||
Running Puppeteer on Heroku requires some additional dependencies that aren't
|
||||
included on the Linux box that Heroku spins up for you. To add the dependencies
|
||||
on deploy, add the Puppeteer Heroku buildpack to the list of buildpacks for your
|
||||
app under Settings > Buildpacks.
|
||||
|
||||
The url for the buildpack is https://github.com/jontewks/puppeteer-heroku-buildpack
|
||||
The url for the buildpack is
|
||||
https://github.com/jontewks/puppeteer-heroku-buildpack
|
||||
|
||||
Ensure that you're using `'--no-sandbox'` mode when launching Puppeteer. This can be done by passing it as an argument to your `.launch()` call: `puppeteer.launch({ args: ['--no-sandbox'] });`.
|
||||
Ensure that you're using `'--no-sandbox'` mode when launching Puppeteer. This
|
||||
can be done by passing it as an argument to your `.launch()` call:
|
||||
`puppeteer.launch({ args: ['--no-sandbox'] });`.
|
||||
|
||||
When you click add buildpack, simply paste that url into the input, and click save. On the next deploy, your app will also install the dependencies that Puppeteer needs to run.
|
||||
When you click add buildpack, simply paste that url into the input, and click
|
||||
save. On the next deploy, your app will also install the dependencies that
|
||||
Puppeteer needs to run.
|
||||
|
||||
If you need to render Chinese, Japanese, or Korean characters you may need to use a buildpack with additional font files like https://github.com/CoffeeAndCode/puppeteer-heroku-buildpack
|
||||
If you need to render Chinese, Japanese, or Korean characters you may need to
|
||||
use a buildpack with additional font files like
|
||||
https://github.com/CoffeeAndCode/puppeteer-heroku-buildpack
|
||||
|
||||
There's also another [simple guide](https://timleland.com/headless-chrome-on-heroku/) from @timleland that includes a sample project: https://timleland.com/headless-chrome-on-heroku/.
|
||||
There's also another
|
||||
[simple guide](https://timleland.com/headless-chrome-on-heroku/) from @timleland
|
||||
that includes a sample project:
|
||||
https://timleland.com/headless-chrome-on-heroku/.
|
||||
|
||||
### Running Puppeteer on AWS Lambda
|
||||
|
||||
AWS Lambda [limits](https://docs.aws.amazon.com/lambda/latest/dg/limits.html) deployment package sizes to ~50MB. This presents challenges for running headless Chrome (and therefore Puppeteer) on Lambda. The community has put together a few resources that work around the issues:
|
||||
AWS Lambda [limits](https://docs.aws.amazon.com/lambda/latest/dg/limits.html)
|
||||
deployment package sizes to ~50MB. This presents challenges for running headless
|
||||
Chrome (and therefore Puppeteer) on Lambda. The community has put together a few
|
||||
resources that work around the issues:
|
||||
|
||||
- https://github.com/alixaxel/chrome-aws-lambda (kept updated with the latest stable release of puppeteer)
|
||||
- https://github.com/adieuadieu/serverless-chrome/blob/HEAD/docs/chrome.md (serverless plugin - outdated)
|
||||
- https://github.com/alixaxel/chrome-aws-lambda (kept updated with the latest
|
||||
stable release of puppeteer)
|
||||
- https://github.com/adieuadieu/serverless-chrome/blob/HEAD/docs/chrome.md
|
||||
(serverless plugin - outdated)
|
||||
|
||||
### Running Puppeteer on AWS EC2 instance running Amazon-Linux
|
||||
|
||||
If you are using an EC2 instance running amazon-linux in your CI/CD pipeline, and if you want to run Puppeteer tests in amazon-linux, follow these steps.
|
||||
If you are using an EC2 instance running amazon-linux in your CI/CD pipeline,
|
||||
and if you want to run Puppeteer tests in amazon-linux, follow these steps.
|
||||
|
||||
1. To install Chromium, you have to first enable `amazon-linux-extras` which comes as part of [EPEL (Extra Packages for Enterprise Linux)](https://aws.amazon.com/premiumsupport/knowledge-center/ec2-enable-epel/):
|
||||
1. To install Chromium, you have to first enable `amazon-linux-extras` which
|
||||
comes as part of
|
||||
[EPEL (Extra Packages for Enterprise Linux)](https://aws.amazon.com/premiumsupport/knowledge-center/ec2-enable-epel/):
|
||||
|
||||
```sh
|
||||
sudo amazon-linux-extras install epel -y
|
||||
@@ -465,13 +572,23 @@ If you are using an EC2 instance running amazon-linux in your CI/CD pipeline, an
|
||||
sudo yum install -y chromium
|
||||
```
|
||||
|
||||
Now Puppeteer can launch Chromium to run your tests. If you do not enable EPEL and if you continue installing chromium as part of `npm install`, Puppeteer cannot launch Chromium due to unavailablity of `libatk-1.0.so.0` and many more packages.
|
||||
Now Puppeteer can launch Chromium to run your tests. If you do not enable EPEL
|
||||
and if you continue installing chromium as part of `npm install`, Puppeteer
|
||||
cannot launch Chromium due to unavailablity of `libatk-1.0.so.0` and many more
|
||||
packages.
|
||||
|
||||
## Code Transpilation Issues
|
||||
|
||||
If you are using a JavaScript transpiler like babel or TypeScript, calling `evaluate()` with an async function might not work. This is because while `puppeteer` uses `Function.prototype.toString()` to serialize functions while transpilers could be changing the output code in such a way it's incompatible with `puppeteer`.
|
||||
If you are using a JavaScript transpiler like babel or TypeScript, calling
|
||||
`evaluate()` with an async function might not work. This is because while
|
||||
`puppeteer` uses `Function.prototype.toString()` to serialize functions while
|
||||
transpilers could be changing the output code in such a way it's incompatible
|
||||
with `puppeteer`.
|
||||
|
||||
Some workarounds to this problem would be to instruct the transpiler not to mess up with the code, for example, configure TypeScript to use latest ecma version (`"target": "es2018"`). Another workaround could be using string templates instead of functions:
|
||||
Some workarounds to this problem would be to instruct the transpiler not to mess
|
||||
up with the code, for example, configure TypeScript to use latest ecma version
|
||||
(`"target": "es2018"`). Another workaround could be using string templates
|
||||
instead of functions:
|
||||
|
||||
```ts
|
||||
await page.evaluate(`(async() => {
|
||||
|
||||
Reference in New Issue
Block a user