The Node.js Runtime


The Node.js runtime is the software stack responsible for installing your application's code and its dependencies and running your application. The standard runtime is declared in app.yaml as runtime: nodejs:

runtime: nodejs
vm: true

Runtimes in the flexible environment are built using Docker. The Node.js runtime is based on Debian Jessie, and the source code for the Node.js runtime is publicly available on GitHub.


The default Node.js engine is currently Node.js 4.6.0. You can specify a different Node.js version in your application's package.json file by using the engines field. Here is an example that configures the runtime to use Node.js v0.12.7:

  "engines": {
    "node": "0.12.7"

When engines is specified, the runtime attempts to download and install the specified version of Node.js. If the version cannot be satisfied, you will receive an error message when deploying your application.


During deployment, the runtime uses npm install to install all dependencies declared in package.json. For more information about managing Node.js packages on Google App Engine, see Using Node.js Libraries.

To enable the use of Node.js packages that require native extensions, the following Debian packages are pre-installed in the Docker image.

If your application requires additional operating-system-level dependencies, you will need to use a custom runtime based on this runtime to install the appropriate packages.

Application startup

The runtime starts your application by using npm start, which uses the command specified in package.json. For example:

"scripts": {
  "start": "node app.js"

Your start script should start a web server that responds to HTTP requests on the port specified by the PORT environment variable, typically 8080.

Extending the runtime

The standard Node.js runtime can be used to create a custom runtime. To do this, use gcloud beta app gen-config --custom to create the base Dockerfile and .dockerignore files. You can then customize these files as needed. Note that if you create Dockerfile, you must specify runtime: custom instead of runtime: nodejs in your app.yaml file.

HTTPS and forwarding proxies

App Engine terminates the HTTPS connection at the load balancer and forwards the request to your application. Some applications need to determine the original request IP and protocol. The user's IP address is available in the standard X-Forwarded-For header as well as the X-Appengine-User-Ip header. Applications that require this information should configure their web framework to trust the proxy. With Express.js you would use the trust_proxy setting:

app.set('trust proxy', true);

Note that App Engine does not set the X-Forwarded-Proto header to indicate that the original connection was sent over HTTPS as expected by some frameworks. Instead, applications should check that the value of the X-AppEngine-Https is set to "on".

To ensure that Express.js sets correctly, add the following middleware to your application right below where you set the trust proxy setting:

app.use(function (req, res, next) {
  if (req.get('x-appengine-https') === 'on' && !req.get('x-forwarded-proto')) {
    req.headers['x-forwarded-proto'] = 'https';

Environment variables

The following environment variables are set by the runtime environment:

  • PORT is set to 8080.
  • NODE_ENV is set to production.
  • GAE_LONG_APP_ID is set to the Project ID associated with your application, which is visible in the Google Cloud Platform Console.
  • GAE_MODULE_NAME is set to the module name specified in your application's app.yaml file, or if no module name is specified, it is set to default.
  • GAE_APPENGINE_HOSTNAME is set to the hostname for your application, typically <your-project-id>

You can set additional environment variables with app.yaml.

Metadata server

Each instance of your application can use the Compute Engine metadata server to query information about the instance, including its host name, external IP address, instance ID, custom metadata, and service account information. App Engine does not allow you to set custom metadata for each instance, but you can set project-wide custom metadata and read it from your App Engine and Compute Engine instances.

This example function uses the metadata server to get the external IP address of the instance:

// In order to use websockets on App Engine, you need to connect directly to
// application instance using the instance's public external IP. This IP can
// be obtained from the metadata server.
var METADATA_NETWORK_INTERFACE_URL = 'http://metadata/computeMetadata/v1/' +

function getExternalIp (cb) {
  var options = {
    headers: {
      'Metadata-Flavor': 'Google'

  request(options, function (err, resp, body) {
    if (err || resp.statusCode !== 200) {
      console.log('Error while talking to metadata server, assuming localhost');
      return cb('localhost');
    return cb(body);

Send feedback about...

App Engine flexible environment for Node.js docs