Elastic Beanstalk
Developer Guide (API Version 2010-12-01)
Did this page help you?  Yes | No |  Tell us about it...
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Go to the Kindle Store to download this guide in Kindle format.

Configuring Node.js Containers with Elastic Beanstalk

You can fine-tune the behavior of your Amazon EC2 instances by using a configuration file to configure your container settings. For instructions on customizing and configuring a Node.js container, see Customizing and Configuring a Node.js Environment. For a list of container options, see Node.js Container Options.

The Container/Node.js Options configuration also 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 with the AWS Management Console.

Customizing and Configuring a Node.js Environment

When deploying your Node.js application, you may want to customize and configure the behavior of your EC2 instances. You can easily customize your instances at the same time that you deploy your application version by including a configuration file with your source bundle. This section walks you through the process of creating a configuration file and bundling it with your source. For an example walkthrough using configuration files, see Deploying an Express Application to Elastic Beanstalk.

To customize and configure your Node.js environment

  1. Create a configuration file with the extension .config (e.g., myapp.config) and place it in an .ebextensions top-level directory of your source bundle. You can have multiple configuration files in your .ebextensions directory. These files are executed in alphabetical order. For example, .ebextensions/01run.config is executed before .ebextensions/02do.config.

    Note

    Configuration files must conform to YAML or JSON formatting standards. For example, indentation is critical to the proper interpretation of YAML. For more information, go to http://www.yaml.org/start.html or http://www.json.org, respectively. For more information about using configuration files to deploy an application to Elastic Beanstalk, see Using Configuration Files.

    The following is an example snippet of a configuration file. For a full list of Node.js container options, see Node.js Container Options.

    option_settings:
      - namespace: aws:elasticbeanstalk:container:nodejs
        option_name: ProxyServer
        value: nginx
      - namespace: aws:elasticbeanstalk:container:nodejs:staticfiles
        option_name: /public
        value: /public

    Note

    You can specify any key-value pairs in the aws:elasticbeanstalk:application:environment namespace, and they will be passed in as environment variables on your EC2 instances.

  2. Create a package.json file and place it in the top-level directory of your source bundle. A typical Node.js application will have dependencies on other third-party packages. You specify all the packages you need (as well as their versions) in a single package.json file. For more information about the requirements file, see package.json on the NPM website. The following is an example package.json file for the Express framework.

    {
      "name": "application-name",
      "version": "0.0.1",
      "private": true,
      "scripts": {
        "start": "node app"
      },
      "dependencies": {
        "express": "3.1.0",
        "jade": "*",
        "mysql": "*",
        "async": "*",
        "node-uuid": "*"
      }
    }
  3. Deploy your application version.

For an example walkthrough of deploying an Express application, see Deploying an Express Application to Elastic Beanstalk . For an example walkthrough of deploying a Geddy application with Amazon ElastiCache, see Deploying a Geddy Application with Clustering to Elastic Beanstalk.

Accessing Environment Configuration Settings

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.

process.env.PARAM1
process.env.PARAM2

Note

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

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

Example: Using Configuration Files to Configure Nginx and Apache

You can use configuration files to make modifications to Apache. For example, if you want to configure Nginx or Apache to server application/json gzipped, which is not on by default, you would create a configuration file with the following snippets.

Example 1. Example configuring Nginx

files:
  /etc/nginx/conf.d/gzip.conf:
    content: |
      gzip_types application/json;

Example 2. Example configuring Apache

files:
  /etc/httpd/conf.d/gzip.conf:
    content: |
      AddOutputFilterByType DEFLATE application/json

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 at https://console.aws.amazon.com/elasticbeanstalk/.

  2. From the Elastic Beanstalk console applications page, click the environment that you want to configure.

  3. In the Overview section of the environment dashboard, click Edit.

  4. On the Configuration page, click Edit for Software Configuration in order to edit the container settings.

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 affect, and gzip compression is disabled.

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

    Note

    When support for the version of Node.js that you are using is removed from the platform configuration, you must change 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 will fail. 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, 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.

Accessing Environment Configuration Settings

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.

process.env.PARAM1
process.env.PARAM2

Note

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

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

Command Line Interface (CLI)

To edit an application's environment configuration settings

  • Update an application's environment configuration settings.

    $ aws elasticbeanstalk update-environment --environment-name my-env --option-settings file://options.txt

options.txt

[
    {
        "Namespace": "aws:elasticbeanstalk:container:nodejs:staticfiles",
        "OptionName": "/public",
        "Value": "/public"
    },
    {
        "Namespace": "aws:elasticbeanstalk:container:nodejs",
        "OptionName": "ProxyServer",
        "Value": "nginx"
    },
    {
        "Namespace": "aws:elasticbeanstalk:container:nodejs",
        "OptionName": "NodeCommand",
        "Value": ""
    },
    {
        "Namespace": "aws:elasticbeanstalk:container:nodejs",
        "OptionName": "NodeVersion",
        "Value": "0.8.18"
    },
    {
        "Namespace": "aws:elasticbeanstalk:container:nodejs",
        "OptionName": "GzipCompression",
        "Value": "true"
    },
    {
        "Namespace": "aws:elasticbeanstalk:application:environment",
        "OptionName": "AWS_ACCESS_KEY_ID",
        "Value": "AKIAIOSFODNN7EXAMPLE"
    },
    {
        "Namespace": "aws:elasticbeanstalk:application:environment",
        "OptionName": "AWS_SECRET_KEY",
        "Value": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
    },
    {
        "Namespace": "aws:elasticbeanstalk:application:environment",
        "OptionName": "myvar",
        "Value": "somevalue"
    },
    {
        "Namespace": "aws:elasticbeanstalk:hostmanager",
        "OptionName": "LogPublicationControl",
        "Value": "false"
    }
]

API

To edit an application's environment configuration settings

  • Call UpdateEnvironment with the following parameters:

    • EnvironmentName = SampleAppEnv

    • OptionSettings.member.1.Namespace = aws:elasticbeanstalk:container:nodejs:staticfiles

    • OptionSettings.member.1.OptionName = /public

    • OptionSettings.member.1.Value = /public

    • OptionSettings.member.2.Namespace = aws:elasticbeanstalk:container:nodejs

    • OptionSettings.member.2.OptionName = ProxyServer

    • OptionSettings.member.2.Value = nginx

    • OptionSettings.member.3.Namespace = aws:elasticbeanstalk:container:nodejs

    • OptionSettings.member.3.OptionName = NodeCommand

    • OptionSettings.member.3.Value = ""

    • OptionSettings.member.4.Namespace = aws:elasticbeanstalk:container:nodejs

    • OptionSettings.member.4.OptionName = NodeVersion

    • OptionSettings.member.4.Value = 0.8.18

    • OptionSettings.member.5.Namespace = aws:elasticbeanstalk:container:nodejs

    • OptionSettings.member.5.OptionName = GzipCompression

    • OptionSettings.member.5.Value = true

    • OptionSettings.member.6.Namespace = aws:elasticbeanstalk:application:environment

    • OptionSettings.member.6.OptionName = AWS_ACCESS_KEY_ID

    • OptionSettings.member.6.Value = AKIAIOSFODNN7EXAMPLE

    • OptionSettings.member.7.Namespace = aws:elasticbeanstalk:application:environment

    • OptionSettings.member.7.OptionName = AWS_SECRET_KEY

    • OptionSettings.member.7.Value = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

    • OptionSettings.member.8.Namespace = aws:elasticbeanstalk:application:environment

    • OptionSettings.member.8.OptionName = myvar

    • OptionSettings.member.8.Value = somevalue

    • OptionSettings.member.9.Namespace = aws:elasticbeanstalk:hostmanager

    • OptionSettings.member.9.OptionName = LogPublicationControl

    • OptionSettings.member.9.Value = false

    Example

    https://elasticbeanstalk.us-west-2.amazon.com/?EnvironmentName=SampleAppEnv
    &OptionSettings.member.1.Namespace=aws%3Aelasticbeanstalk%3Acontainer%3Anodejs%3Astaticfiles
    &OptionSettings.member.1.OptionName=/public
    &OptionSettings.member.1.Value=/public
    &OptionSettings.member.2.Namespace=aws%3Aelasticbeanstalk%3Acontainer%3Anodejs
    &OptionSettings.member.2.OptionName=ProxyServer
    &OptionSettings.member.2.Value=nginx
    &OptionSettings.member.3.Namespace=aws%3Aelasticbeanstalk%3Acontainer%3Anodejs
    &OptionSettings.member.3.OptionName=NodeCommand
    &OptionSettings.member.3.Value=""
    &OptionSettings.member.4.Namespace=aws%3Aelasticbeanstalk%3Acontainer%3Anodejs
    &OptionSettings.member.4.OptionName=NodeVersion
    &OptionSettings.member.4.Value=0.8.18
    &OptionSettings.member.5.Namespace=aws%3Aelasticbeanstalk%3Acontainer%3Anodejs
    &OptionSettings.member.5.OptionName=GzipCompression
    &OptionSettings.member.5.Value=true
    &OptionSettings.member.6.Namespace=aws%3Aelasticbeanstalk%3Aapplication%3Aenvironment
    &OptionSettings.member.6.OptionName=AWS_ACCESS_KEY_ID
    &OptionSettings.member.6.Value=AKIAIOSFODNN7EXAMPLE
    &OptionSettings.member.7.Namespace=aws%3Aelasticbeanstalk%3Aapplication%3Aenvironment
    &OptionSettings.member.7.OptionName=AWS_SECRET_KEY
    &OptionSettings.member.7.Value=wJalrXUtnFEMI%2FK7MDENG%2FbPxRfiCYEXAMPLEKEY
    &OptionSettings.member.8.Namespace=aws%3Aelasticbeanstalk%3Aapplication%3Aenvironment
    &OptionSettings.member.8.OptionName=myvar
    &OptionSettings.member.8.Value=somevalue
    &OptionSettings.member.9.Namespace=aws%3Aelasticbeanstalk%3Ahostmanager
    &OptionSettings.member.9.OptionName=LogPublicationControl
    &OptionSettings.member.9.Value=false
    &Operation=UpdateEnvironment
    &AuthParams