Running Chrome Headless on Linux

You've written your Puppeteer code, you've made sure it works, and now it's time to get your project running someplace. This might be on a hosting provider like Amazon Web Services or on your own hardware. In any case chances are that you're running some flavor of Linux, and if you're reading this then you've undoubtedly run into some issues getting Chrome to run properly.

1. Downloading Chrome

Before we even begin going over how to get Chrome running, let's talk about which version of Chrome we want. Most folks will reach for some sort of Personal Package Archives (PPA) to do this installation, however if you're using puppeter then I'd heavily recommend using its bundled version of Chromium since that'll spare you a lot of headache. It's as simple as installing it via npm:

# Install puppeteer
$ npm i --save puppeteer

# OR just install your package deps
$ npm i

This is merely the beginning as you'll need a few other packages as well to get Chrome running properly.

2. Getting Chrome's dependencies

If you've followed the advice in Step #1, then you'll likely need a few other packages to get things running smoothly (ok, a lot of other packages). If you've ever seen this error then you'll know what I mean.

# Common errors running puppeteer on linux
Unhandled promise rejection (rejection id: 1): Error: Failed to launch chrome!

The issue here is that the Chrome binary that comes bundled with Puppeteer actually requires quite a few sub-dependencies. It's an easy issue to fix if you know what to install. Simply run the following:

# Install all of Chrome's necessary packages
apt-get update && apt-get install -y \
  locales \
  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 \
  libappindicator1 \
  libnss3 \
  lsb-release \
  xdg-utils

Once this is done, you're nearly there!

3. Make sure Node is installed

This probably goes without saying, but you'll obviously want NodeJS installed if you're going to use puppeteer, so let's get that going as well.

# Install NodeJS
$ apt-get install -y curl &&\
  curl --silent --location https://deb.nodesource.com/setup_8.x | bash - &&\
  apt-get install -y nodejs build-essential

Once that's done you should have everything you need to get Chrome, and puppeteer, working on your linux box!

Next Steps

There's actually a lot more that you'll likely need or issues you'll run into at a certain point. Chrome is pretty resource-intensive so you'll want to have some sort of management layer around it, and we haven't even begun looking into all the missing fonts you'll likely need (especially for Asian characters). If you're running into these issues then definitely take a look at our Dockerfile as it contains all the packages you'll need to get started (and if not file an issue on GitHub).

Thanks for reading, and best of luck on your project!