AWS Elastic Beanstalk
Developer Guide (last updated: 12 December, 2014) (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.

Customizing the Software on EC2 Instances Running Linux

You may want to customize and configure the software that your application depends on. These files could be either dependencies required by the application—for example, additional packages from the yum repository—or they could be configuration files such as a replacement for httpd.conf to override specific settings that are defaulted by AWS Elastic Beanstalk.

This section describes the type of information you can include in a configuration file to customize the software on your EC2 instances running Linux. For general information on customizing and configuring your AWS Elastic Beanstalk environments, see Customizing and Configuring AWS Elastic Beanstalk Environments. For information on customizing software on your EC2 instances running Windows, see Customizing the Software on EC2 Instances Running Windows.

Configuration files should 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 AWS Elastic Beanstalk, see Using Configuration Files.

The order in which these are processed are as follows:

  1. Packages

  2. Files

  3. Commands

  4. Services

  5. Container Commands

Packages

You can use the packages key to download and install prepackaged applications and components.

Syntax

packages: 
  <name of package manager>:
    <package name>: <version> 

Supported Package Formats

AWS Elastic Beanstalk currently supports the following package managers: yum, rubygems, python, and rpm. Packages are processed in the following order: rpm, yum, and then rubygems and python. There is no ordering between rubygems and python, and packages within each package manager are not guaranteed to be installed in any order. Use a package manager supported by your operating system.

Note

AWS Elastic Beanstalk supports two underlying package managers for Python, pip and easy_install. However, in the syntax of the configuration file, you must specify the package manager name as python. When you use a configuration file to specify a Python package manager, AWS Elastic Beanstalk uses Python 2.6. If your application relies on a different version of Python, you can specify the packages to install in a requirements.txt file. For more information, see Customizing and Configuring a Python Container.

Specifying Versions

Within each package manager, each package is specified as a package name and a list of versions. The version can be a string, a list of versions, or an empty string or list. An empty string or list indicates that you want the latest version. For rpm manager, the version is specified as a path to a file on disk or a URL. Relative paths are not supported.

If you specify a version of a package, AWS Elastic Beanstalk attempts to install that version even if a newer version of the package is already installed on the instance. If a newer version is already installed, the deployment fails. Some package managers support multiple versions, but others may not. Please check the documentation for your package manager for more information. If you do not specify a version and a version of the package is already installed, AWS Elastic Beanstalk does not install a new version—it assumes that you want to keep and use the existing version.

Example Snippet

The following snippet specifies a version URL for rpm, requests the latest version from yum and apt, and version 0.10.2 of chef from rubygems.

packages: 
  yum:
    libmemcached: [] 
    ruby-devel: []
    gcc: []
  rpm:
    epel: http://download.fedoraproject.org/pub/epel/5/i386/epel-release-5-4.noarch.rpm
  rubygems: 
    chef: '0.10.2'
  apt:
    mysql-client: []

Sources

You can use the sources key to download an archive file and unpack it in a target directory on the EC2 instance. Sources does not automatically build the unpacked sources.

Syntax

sources:  
  <target directory>: <location of archive file>

Supported Formats

Supported formats are tar, tar+gzip, tar+bz2, and zip. You can reference external locations such as Amazon Simple Storage Service (Amazon S3) (e.g., http://s3.amazonaws.com/mybucket/myobject).

Example Snippet

The following example downloads a .zip file from an Amazon S3 bucket and unpacks it into /etc/myapp:

sources:  
  /etc/myapp: http://s3.amazonaws.com/mybucket/myobject 

Files

You can use the files key to create files on the EC2 instance. The content can be either inline in the configuration file, or the content can be pulled from a URL. The files are written to disk in lexicographic order. You can reference external locations such as Amazon S3 (e.g., http://s3.amazonaws.com/mybucket/myobject). The following table lists the supported keys.

Syntax

files:  
  "<target file location on disk>": 
     mode: "<six-digit octal value>"
     owner: <name of owning user for file>
     group: <name of owning group for file>
     source: <URL>
     authentication: <authentication name>:
						
  "<target file location on disk>": 
     mode: "<six-digit octal value>"
     owner: <name of owning user for file>
     group: <name of owning group for file>
     content: |
	   this is my content
     encoding: encoding format
     authentication: <authentication name>:   

Options

KeyDescription

content

A string.

source

A URL to load the file from. This option cannot be specified with the content key.

encoding

The encoding format. Only used if the content is a string. Encoding is not applied if you are using a source.

Valid values: plain | base64

group

The name of the owning group for this file.

owner

The name of the owning user for this file.

mode

A six-digit octal value representing the mode for this file (e.g, "000444"). The first three digits are used for symlinks and the last three digits are used for setting permissions.

authentication

The name of an authentication method to use. This overrides any default authentication.

Example Snippet

files:
  "/home/ec2-user/myfile" :
    mode: "000755"
    owner: root
    group: root
    source: http://foo.bar/myfile
 
  "/home/ec2-user/myfile2" :
    mode: "000755"
    owner: root
    group: root
    content: |
      # this is my file
      # with content

Example using a symlink. This creates a link /tmp/myfile2.txt that points at the existing file /tmp/myfile1.txt.

files:
  "/tmp/myfile2.txt" :
    mode: "120400"
    content: "/tmp/myfile1.txt"

Users

You can use the users key to create Linux/UNIX users on the EC2 instance.

Syntax

users:
  <name of user>:
    groups:
      - <name of group>
    uid: "<id of the user>"
    homeDir: "<user's home directory>"

Options

KeyDescription

uid

A user ID. The creation process fails if the user name exists with a different user ID. If the user ID is already assigned to an existing user, the operating system may reject the creation request.

groups

A list of group names. The user is added to each group in the list.

homeDir

The user's home directory.

Users are created as noninteractive system users with a shell of /sbin/nologin. This is by design and cannot be modified.

Example Snippet

users:
  myuser:
    groups:
      - group1
      - group2
    uid: "50"
    homeDir: "/tmp"

Groups

You can use the groups key to create Linux/UNIX groups and to assign group IDs. To create a group, add a new key-value pair that maps a new group name to an optional group ID. The groups key can contain one or more group names. The following table lists the available keys.

Syntax

groups:
  <name of group>:
  <name of group>:
    gid: "<group id>"

Options

KeyDescription

gid

A group ID number.

If a group ID is specified, and the group already exists by name, the group creation will fail. If another group has the specified group ID, the operating system may reject the group creation.

Example Snippet

The following snippet specifies a group named groupOne without assigning a group ID and a group named groupTwo that specified a group ID value of 45.

groups:
  groupOne:
  groupTwo:
    gid: "45"

Commands

You can use the commands key to execute commands on the EC2 instance. The commands are processed in alphabetical order by name, and they run before the application and web server are set up and the application version file is extracted.

Syntax

commands:
  test_command: 
    command: <command to run>
    cwd: <working directory>
    env: 
      <variable name>: <variable value>
    test: <conditions for command> 
    ignoreErrors: true

Options

KeyDescription

command

Required. Either an array or a string specifying the command to run. If you use an array, you do not need to escape space characters or enclose command parameters in quotes.

env

Optional. Sets environment variables for the command. This property overwrites, rather than appends, the existing environment.

cwd

Optional. The working directory. By default, AWS Elastic Beanstalk attempts to find the directory location of your project. If not found, then "/" is used.

test

Optional. A command that must return the value true (exit code 0) in order for AWS Elastic Beanstalk to process the command (e.g., a bash script) contained in the command key.

ignoreErrors

Optional. A boolean value that determines if other commands should run if the command contained in the command key fails (returns a nonzero value). Set this value to true if you want to continue running commands even if the command fails. Set it to false if you want to stop running commands if the command fails. The default value is false.

Example Snippet

The following example snippet runs a python script.

commands:
  python_install: 
    command: myscript.py
    cwd: /home/ec2-user
    env: 
      myvarname: myvarvalue
    test: '[ ! /usr/bin/python ] && echo "python not installed"'

Container_commands

You can use the container_commands key to execute commands for your container. The commands in container_commands are processed in alphabetical order by name. They run after the application and web server have been set up and the application version file has been extracted, but before the application version is deployed. They also have access to environment variables such as your AWS security credentials. Additionally, you can use leader_only. One instance is chosen to be the leader in an Auto Scaling group. If the leader_only value is set to true, the command runs only on the instance that is marked as the leader.

Syntax

container_commands:
 <name of container_command>:
    command: "<command to run>"
    leader_only: true
 <name of container_command>:
    command: "<command to run>"

Options

KeyDescription

command

Required. Either an array or a string specifying the command to run. If you use an array, you do not need to escape space characters or enclose command parameters in quotes.

env

Optional. Sets environment variables for the command. This property overwrites, rather than appends, the existing environment.

cwd

Optional. The working directory. By default, this is the directory of the unzipped application.

leader_only

Optional. Sets an instance in the Auto Scaling group to be the leader. If the leader_only value is set to true, the command runs only on the instance that is marked as the leader. The leader runs first.

test

Optional. A command that must return the value true in order for AWS Elastic Beanstalk to process the command contained in the command key. If this option is set to true, it overrides the leader_only setting.

ignoreErrors

Optional. A boolean value that determines if other commands should run if the command contained in the command key fails (returns a nonzero value). Set this value to true if you want to continue running commands even if the command fails. Set it to false if you want to stop running commands if the command fails. The default value is false.

Example Snippet

The following is an example snippet.

container_commands:
  collectstatic:
    command: "django-admin.py collectstatic --noinput"
  01syncdb:
    command: "django-admin.py syncdb --noinput"
    leader_only: true
  02migrate:
    command: "django-admin.py migrate"
    leader_only: true
  99customize:
    command: "scripts/customize.sh"

Services

You can use the services key to define which services should be started or stopped when the instance is launched. The services key also allows you to specify dependencies on sources, packages, and files so that if a restart is needed due to files being installed, AWS Elastic Beanstalk takes care of the service restart.

Syntax

services: 
  sysvinit:
    <name of service>:
      enabled: true
      ensureRunning: true
      files: "<file name>"
      sources: "<directory>"	
      packages: 
        <name of package manager>:
          <package name>: <version>
      commands: 
        <name of command>

Options

The following table lists the supported keys.

KeyDescription

ensureRunning

Set to true to ensure that the service is running after AWS Elastic Beanstalk finishes.

Set to false to ensure that the service is not running after AWS Elastic Beanstalk finishes.

Omit this key to make no changes to the service state.

enabled

Set to true to ensure that the service is started automatically upon boot.

Set to false to ensure that the service is not started automatically upon boot.

Omit this key to make no changes to this property.

files

A list of files. If AWS Elastic Beanstalk changes one directly via the files block, the service is restarted.

sources

A list of directories. If AWS Elastic Beanstalk expands an archive into one of these directories, the service is restarted.

packages

A map of the package manager to a list of package names. If AWS Elastic Beanstalk installs or updates one of these packages, the service is restarted.

commands

A list of command names. If AWS Elastic Beanstalk runs the specified command, the service is restarted.

Example Snippet

The following is an example snippet:

services: 
  sysvinit:
    myservice:
      enabled: true
      ensureRunning: true

Option_settings

Option_settings enables you to modify the Elastic Beanstalk configuration and define variables that can be retrieved from your application using environment variables. The following table displays the namespaces that are supported for each container type. Some namespaces allow you to extend the number of parameters, and specify the parameter names. For a list of configuration settings, see Option Values.

Syntax

option_settings:
  - namespace:  <namespace>
    option_name:  <option name>
    value:  <option value>
  - option_name:  <option name>
    value:  <option value>

Options

ContainerNamespaceExtend
Java

aws:elasticbeanstalk:application:environment

aws:elasticbeanstalk:container:tomcat:jvmoptions

Yes

Yes

Node.js

aws:elasticbeanstalk:application:environment

aws:elasticbeanstalk:container:nodejs

aws:elasticbeanstalk:container:nodejs:staticfiles

Yes

No

Yes

PHP

aws:elasticbeanstalk:application:environment

aws:elasticbeanstalk:container:php:phpini

Yes

No

Python

aws:elasticbeanstalk:application:environment

aws:elasticbeanstalk:container:python

aws:elasticbeanstalk:container:python:staticfiles

Yes

No

Yes

Ruby

aws:elasticbeanstalk:application:environment

Yes

Note

If you do not specify a namespace, the default used is aws:elasticbeanstalk:application:environment.

Example Snippet

The following is an example snippet.

option_settings:
  - namespace:  aws:elasticbeanstalk:container:tomcat:jvmoptions
    option_name:  Xmx
    value:  256m
  - option_name: myparam1
    value: somevalue

Accessing Environment Variables

The parameters specified in the option_settings section of the configuration file are passed in as environment variables to the EC2 instances. For coding examples, see the following sections: