Edit on GitHub
Report issue
Page history

Extending the Node.js runtime of App Engine flexible environment

Author(s): @jmdobry ,   Published: 2017-01-23

This tutorial shows how to extend the Node.js runtime of the App Engine flexible environment.

You will create a small Node.js web application that requires customizations to the default Node.js runtime of the App Engine flexible environment.


  1. Create a project in the Google Cloud Platform Console.
  2. Enable billing for your project.
  3. Install the Google Cloud SDK.


  1. Initialize a package.json file with the following command:

    npm init
  2. Install Express.js:

    npm install --save express
  3. Create an app.yaml file with the following contents:

    runtime: nodejs
    env: flex

Creating the app

  1. Create a file named server.js with the following contents:

    [embedmd]:# (server.js)

    'use strict';
    const exec = require('child_process').exec;
    const express = require('express');
    const app = express();
    app.get('/', (req, res, next) => {
      // Get the output from the "fortune" program. This is installed into the
      // environment by the Dockerfile.
      exec('/usr/games/fortune', (err, stdout) => {
        if (err) {
        res.set('Content-Type', 'text/plain');
    if (module === require.main) {
      const PORT = process.env.PORT || 8080;
      app.listen(PORT, () => {
        console.log(`App listening on port ${PORT}`);
        console.log('Press Ctrl+C to quit.');
    module.exports = app;

Notice how the app shells out to /usr/games/fortune in order to respond to the request. The fortune binary is not available in the default Node.js runtime, so you need to extend the runtime in order to make the binary available to your app after it's deployed.

Extending the runtime

  1. Run the following command to extend the runtime:

    gcloud beta app gen-config --custom

    This will generate Dockerfile and .dockerignore files, and modify the app.yaml file to include runtime: custom instead of runtime: nodejs.

  2. Modify the generated Dockerfile to look like the following:

    # Dockerfile extending the generic Node image with application files for a
    # single application.
    FROM gcr.io/google_appengine/nodejs
    # Install the fortunes game
    RUN apt-get update && apt-get install -y fortunes
    # Check to see if the the version included in the base runtime satisfies
    # '>=6.9.0', if not then do an npm install of the latest available
    # version that satisfies it.
    RUN /usr/local/bin/install_node '>=6.9.0'
    # Copy application code.
    COPY . /app/
    # You have to specify "--unsafe-perm" with npm install
    # when running as root.  Failing to do this can cause
    # install to appear to succeed even if a preinstall
    # script fails, and may have other adverse consequences
    # as well.
    # This command will also cat the npm-debug.log file after the
    # build, if it exists.
    RUN npm install --unsafe-perm || \
      ((if [ -f npm-debug.log ]; then \
          cat npm-debug.log; \
        fi) && false)
    # Run the app, default is "npm start"
    CMD npm start

    When the app is deployed, the image will be built using the custom Dockerfile.

You can view the source code and its tests here;

Deploying the app

  1. Run the following command to deploy your app:

    gcloud app deploy
  2. Visit http://YOUR_PROJECT_ID.appspot.com to see the app.

You can check out Node.js and Google Cloud Platform to get an overview of Node.js and learn ways to run Node.js apps on Google Cloud Platform.

Submit a Tutorial

Share step-by-step guides


Request a Tutorial

Ask for community help


GCP Tutorials

Tutorials published by GCP


Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies. Java is a registered trademark of Oracle and/or its affiliates.