AWS Elastic Beanstalk
Developer Guide (API Version 2010-12-01)

Using the AWS Elastic Beanstalk Node.js Platform

The AWS Elastic Beanstalk Node.js platform is a platform configuration for Node.js web applications that can run behind an nginx proxy server, behind an Apache server, or standalone.

Elastic Beanstalk provides configuration options that you can use to customize the software that runs on the EC2 instances in your Elastic Beanstalk environment. You can choose which proxy server to run in front of your application, choose a specific version of Node.js to run, and choose the command used to run your application. You can also configure environment variables needed by your application and enable log rotation to Amazon S3.

Platform-specific configuration options are available in the AWS Management Console for modifying the configuration of a running environment. To avoid losing your environment's configuration when you terminate it, you can use saved configurations to save your settings and later apply them to another environment.

To save settings in your source code, you can include configuration files. Settings in configuration files are applied every time you create an environment or deploy your application. You can also use configuration files to install packages, run scripts, and perform other instance customization operations during deployments.

You can include a Package.json file in your source bundle to install packages during deployment, and an npm-shrinkwrap.json file to lock down dependency versions.

The Node.js platform includes a proxy server to serve static assets, forward traffic to your application, and compress responses. You can extend or override the default proxy configuration for advanced scenarios.

Settings applied in the AWS Management Console override the same settings in configuration files, if they exist. This lets you have default settings in configuration files, and override them with environment specific settings in the console. For more information about precedence, and other methods of changing settings, see Configuration Options.

Configuring Your Node.js Environment in the AWS Management Console

The Node.js settings lets you fine-tune the behavior of your Amazon EC2 instances and enable or disable Amazon S3 log rotation. You can edit the Elastic Beanstalk environment's Amazon EC2 instance configuration using the AWS Management Console.

To access the Node.js container configurations for your Elastic Beanstalk application

  1. Open the Elastic Beanstalk console.

  2. Navigate to the management page for your environment.

  3. Choose Configuration.

  4. In the Software Configuration section, choose the settings icon ( Edit ).

Container Options

On the configuration page, specify the following:

  • Proxy Server– Specifies which web server to use to proxy connections to Node.js. By default, nginx is used. If you select none, static file mappings do not take effect, and gzip compression is disabled.

  • Node Version– Specifies the version of Node.js. For information about what versions are supported, see Elastic Beanstalk Supported Platforms.


    When support for the version of Node.js that you are using is removed from the platform configuration, you must change or remove the version setting prior to doing a platform upgrade. This may occur when a security vulnerability is identified for one or more versions of Node.js

    When this occurs, attempting to upgrade to a new version of the platform that does not support the configured NodeVersion fails. To avoid needing to create a new environment, change the NodeVersion configuration option to a version that is supported by both the old configuration version and the new one, or remove the option setting, and then perform the platform upgrade.

  • Gzip Compression– Specifies whether gzip compression is enabled. By default, gzip compression is enabled.

  • Node Command–Lets you enter the command used to start the Node.js application. An empty string (the default) means Elastic Beanstalk will use app.js, then server.js, and then npm start in that order.

Log Options

The Log Options section has two settings:

  • Instance profile– Specifies the instance profile that has permission to access the Amazon S3 bucket associated with your application.

  • Enable log file rotation to Amazon S3–Specifies whether log files for your application's Amazon EC2 instances should be copied to your Amazon S3 bucket associated with your application.

Static Files

To improve performance, you may want to configure nginx or Apache to server static files (for example, HTML or images) from a set of directories inside your web application. You can set the virtual path and directory mapping on the Container tab in the Static Files section. To add multiple mappings, click Add Path. To remove a mapping, click Remove.

Environment Properties

The Environment Properties section lets you specify environment configuration settings on the Amazon EC2 instances that are running your application. These settings are passed in as key-value pairs to the application.

Inside the Node.js environment running in AWS Elastic Beanstalk, you can access the environment variables using process.env.ENV_VARIABLE similar to the following example.



Environment configuration settings can contain any printable ASCII character except the grave accent (`, ASCII 96) and cannot exceed 200 characters in length.

The Node.js platform sets the PORT environment variable to the port to which the proxy server passes traffic. See Configuring the Proxy Server.

Configuration Files

You can use a configuration file to set configuration options and perform other instance configuration tasks during deployments. The following configuration file tells Elastic Beanstalk to use "npm start" to run the application, sets the proxy type to Apache, enables compression, and configures the proxy to serve static images from the myimages directory at the /images path.

Example .ebextensions/node-settings.config

    NodeCommand: "npm start"
    ProxyServer: apache
    GzipCompression: true
    /images: myimages

For a list of configuration settings, see Node.js Platform Options.

Installing Packages with a Package.json File

Use a package.json file in the root of your project source to use npm to install packages that your application requires.

Example package.json – Express

  "name": "my-app",
  "version": "0.0.1",
  "private": true,
  "dependencies": {
    "ejs": "latest",
    "aws-sdk": "latest",
    "express": "latest",
    "body-parser": "latest"
  "scripts": {
    "start": "node app.js"

When a package.json file is present, Elastic Beanstalk runs npm install to install dependencies.

Locking Dependencies with npm shrinkwrap

The Node.js platform runs npm install each time you deploy. When new versions of your dependencies are available, they will be installed when you deploy your application, potentially causing the deployment to take a long time.

You can avoid upgrading dependencies by creating an npm-shrinkwrap.json file that locks down your application's dependencies to the current version.

$ npm install
$ npm shrinkwrap
wrote npm-shrinkwrap.json

Include this file in your source bundle to ensure that dependencies are only installed once.

Configuring the Proxy Server

The Node.js platform uses a reverse proxy to relay requests from port 80 on the instance to your application listening on port 8081. Elastic Beanstalk provides a default proxy configuration that you can either extend or override completely with your own configuration.

To extend the default configuration, add .conf files to /etc/nginx/conf.d with a configuration file. See Terminating HTTPS on EC2 Instances Running Node.js for an example.

The Node.js platform sets the PORT environment variable to the port to which the proxy server passes traffic. Read this variable in your code to configure your application's port.

    var port = process.env.PORT || 3000;

    var server = app.listen(port, function () {
        console.log('Server running at' + port + '/');

The default nginx configuration forwards traffic to an upstream server named nodejs at It is possible to remove the default configuration and provide your own in a configuration file.

Example .ebextensions/proxy.config

The following example removes the default configuration and adds a custom configuration that forwards traffic to port 5000 instead of 8081.

    mode: "000644"
    owner: root
    group: root
    content: |
      upstream nodejs {
        keepalive 256;

      server {
        listen 8080;

        if ($time_iso8601 ~ "^(\d{4})-(\d{2})-(\d{2})T(\d{2})") {
            set $year $1;
            set $month $2;
            set $day $3;
            set $hour $4;
        access_log /var/log/nginx/healthd/application.log.$year-$month-$day-$hour healthd;
        access_log  /var/log/nginx/access.log  main;

        location / {
            proxy_pass  http://nodejs;
            proxy_set_header   Connection "";
            proxy_http_version 1.1;
            proxy_set_header        Host            $host;
            proxy_set_header        X-Real-IP       $remote_addr;
            proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;

        gzip on;
        gzip_comp_level 4;
        gzip_types text/html text/plain text/css application/json application/x-javascript text/xml application/xml application/xml+rss text/javascript;

        location /static {
            alias /var/app/current/static;


    mode: "000755"
    owner: root
    group: root
    content: |
      #!/bin/bash -xe
      rm -f /etc/nginx/conf.d/00_elastic_beanstalk_proxy.conf
      service nginx stop 
      service nginx start

    command: "rm -f /tmp/deployment/config/#etc#nginx#conf.d#00_elastic_beanstalk_proxy.conf /etc/nginx/conf.d/00_elastic_beanstalk_proxy.conf"

The example configuration, /etc/nginx/conf.d/proxy.conf, uses the default configuration at /etc/nginx/conf.d/00_elastic_beanstalk_proxy.conf as a base to include the default server block with compression and log settings, and a static file mapping.

The removeconfig command removes the container's default configuration to make sure that the proxy server uses the custom configuration. Elastic Beanstalk recreates the default configuration during every configuration deployment. To account for that, the example adds a post-configuration-deployment hook, /opt/elasticbeanstalk/hooks/configdeploy/post/, which removes the default configuration and restarts the proxy server.


The default configuration may change in future versions of the Node.js platform. Use the latest version of the configuration as a base for your customizations to ensure compatibility.

If you override the default configuration, you must define any static file mappings and gzip compression, as the platform will not be able to apply the standard settings.