How to use Puppeteer inside a Docker container
Tags: docker, node, javascript, automation
Published: 2022-03-30 21:30:00

## Introduction

[Puppeteer](https://pptr.dev) is a Node.js library which provides a high-level API to control Chromium (or Firefox) browsers over the DevTools Protocol.

This guide helps to use [Puppeteer](https://pptr.dev) inside a Docker container using the Node.js image.

If we use the Docker images for Node.js v14 LTS Gallium, when installing the `chromium` package from `apt`, it will be v90.0, which can have compatibility issues with the latest Puppeteer. This is because it was tested with the latest Chromium stable release.

## Selecting the correct image

Well... we want to run a web browser inside a container. it's important to know what are the different between the available variants.

### Alpine is enough but ...

Yeah, we can run Chromium using Alpine Linux, but we'll need a few extra steps to make it run. That's why we prefer Debian variants to make it easier.

### Which distro?

Every major version of Node.js in built over a version of Debian, and that Debian version comes with an old version of Chromium, which one could be not compatible with the latest version of Puppeteer.

| **Node.js** | **Debian** | **Chromium**  |
|-------------|------------|---------------|
| v14         | 9.13       | 73.0.3683.75  |
| v16         | 10.9       | 90.0.4430.212 |
| v17         | 11.2       | 99.0.4844.84  |

To quickly solve that issue we can use the Google Chrome's Debian package that always installs the latest stable version. Therefore, this Dockerfile is compatible with Node.js v14, v16, or any new one.

### Why not the built-in Chromium

When we install Google Chrome, `apt` will install all the dependencies for us.

## Dockerfile

```dockerfile
FROM node:slim AS app

# We don't need the standalone Chromium
ENV PUPPETEER_SKIP_CHROMIUM_DOWNLOAD true

# Install Google Chrome Stable and fonts
# Note: this installs the necessary libs to make the browser work with Puppeteer.
RUN apt-get update && apt-get install curl gnupg -y \
  && curl --location --silent https://dl-ssl.google.com/linux/linux_signing_key.pub | apt-key add - \
  && sh -c 'echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" >> /etc/apt/sources.list.d/google.list' \
  && apt-get update \
  && apt-get install google-chrome-stable -y --no-install-recommends \
  && rm -rf /var/lib/apt/lists/*

# Install your app here...
```

💡 If you are in an ARM-based CPU like Apple M1, you should use the `--platform` argument when you build the Docker image.

```bash
docker build --platform linux/amd64 -t image-name .
```

### The code config

Remember to use the installed browser instead of the Puppeteer's built-in one inside your app's code.

```javascript
import puppeteer from 'puppeteer';
...

const browser = await puppeteer.launch({
  executablePath: '/usr/bin/google-chrome',
  args: [...] // if we need them.
});
```

## Conclusion

The browser installation via apt will resolve the required dependencies to run a headless browser inside a Docker container without any manual intervention. These dependencies are not included in the Node.js Docker images by default.

The easiest path to use Puppeteer inside a Docker container is installing Google Chrome because, in contrast to the Chromium package offered by Debian, Chrome only offers the latest stable version.

## Update 2022-08-24

This new Dockerfile version

```dockerfile
FROM node:slim

# We don't need the standalone Chromium
ENV PUPPETEER_SKIP_CHROMIUM_DOWNLOAD true

# Install Google Chrome Stable and fonts
# Note: this installs the necessary libs to make the browser work with Puppeteer.
RUN apt-get update && apt-get install gnupg wget -y && \
  wget --quiet --output-document=- https://dl-ssl.google.com/linux/linux_signing_key.pub | gpg --dearmor > /etc/apt/trusted.gpg.d/google-archive.gpg && \
  sh -c 'echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" >> /etc/apt/sources.list.d/google.list' && \
  apt-get update && \
  apt-get install google-chrome-stable -y --no-install-recommends && \
  rm -rf /var/lib/apt/lists/*
```

Applies the following changes:

A. Removes the `apt-key` deprecation warning.

```
Warning: apt-key is deprecated. Manage keyring files in trusted.gpg.d instead (see apt-key(8)).
```

B. Uses `wget` because it's installed by `google-chrome-stable` and it reduces a few MiB not installing `curl`.