Headless Chrome

Headless Chrome is a headless browser that can be configured on projects like any other service on Platform.sh.

You can interact with the headless-chrome service container using Puppeteer, a Node.js library that provides an API to control Chrome over the DevTools Protocol.

Puppeteer can be used to generate PDFs and screenshots of web pages, automate form submission, and test your project’s UI. You can find out more information about using Puppeteer on GitHub or in their documentation.

Supported versions 

Grid Dedicated Gen 3 Dedicated Gen 2
  • 95
  • 91
  • 86
  • 84
  • 83
  • 81
  • 80
  • 73
None available None available

The following versions aren’t available in the EU-1 and US-1 regions:

  • 95

  • 91

Consider region migration if your project is in those regions.

Relationship 

The format exposed in the $PLATFORM_RELATIONSHIPS environment variable:

{
    "service": "headless",
    "ip": "169.254.73.96",
    "hostname": "3rxha4e2w4yv36lqlypy7qlkza.headless.service._.eu-3.platformsh.site",
    "cluster": "moqwtrvgc63mo-main-7rqtwti",
    "host": "headless.internal",
    "rel": "http",
    "scheme": "http",
    "type": "chrome-headless:73",
    "port": 9222
}

Requirements 

Puppeteer requires at least Node.js version 6.4.0, while using the async and await examples below requires Node 7.6.0 or greater.

Using the Platform.sh Config Reader library requires Node.js 10 or later.

Other languages 

If your app container uses a language other than Node.js, upgrade the Node.js version before using Puppeteer. See how to manage your Node.js version.

Usage example 

1. Configure the service 

To define the service, use the chrome-headless type:

.platform/services.yaml
<SERVICE_NAME>:
    type: chrome-headless:<VERSION>

Note that if you later change the name, it’s treated as an entirely new service. This removes all data from your service. Always backup your data before changing the service.

2. Add the relationship 

To define the relationship, use the http endpoint :

.platform.app.yaml
relationships:
    <RELATIONSHIP_NAME>: "<SERVICE_NAME>:http"

You can define <SERVICE_NAME> and <RELATIONSHIP_NAME> as you like, but it’s best if they’re distinct.

Example Configuration 

Service definition

.platform/services.yaml
headlessbrowser:
    type: chrome-headless:95

App configuration

.platform.app.yaml
relationships:
    chromeheadlessbrowser: "headlessbrowser:http"

Use in app 

After configuration, include Puppeteer as a dependency:

package.json
{
  "dependencies": {
    "puppeteer": "^13.0.1"
  }
}

Using the Node.js Config Reader library, you can retrieve formatted credentials for connecting to headless Chrome with Puppeteer:

const platformsh = require('platformsh-config');

const config = platformsh.config();
const credentials = config.credentials('chromeheadlessbrowser');

and use them to define the browserURL parameter of puppeteer.connect() within an async function:

exports.getBrowser = async function (url) {
    try {
        // Connect to chrome-headless using pre-formatted puppeteer credentials
        const formattedURL = config.formattedCredentials('chromeheadlessbrowser', 'puppeteer');
        const browser = await puppeteer.connect({browserURL: formattedURL});

        ...

        return browser

    } catch (error) {
        console.error({ error }, 'Something happened!');
        browser.close();
    }
};

Puppeteer allows your application to create screenshots, emulate a mobile device, generate PDFs, and much more.

You can find some useful examples of using headless Chrome and Puppeteer on Platform.sh on the Community Portal: