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

Customizing Software on Linux Servers

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 Elastic Beanstalk.

Note

YAML relies on consistent indentation. Match the indentation level when replacing content in an example configuration file and make sure that your text editor uses spaces, not tab characters, to indent.

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 about customizing and configuring your Elastic Beanstalk environments, see AWS Elastic Beanstalk Environment Configuration. For information about customizing software on your EC2 instances running Windows, see Customizing Software on Windows Servers.

Configuration files support the following keys that affect the Linux server your application runs on.

Keys are processed in the order that they are listed above.

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

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

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, 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 Configuration Files.

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, 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, 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 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'

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

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"

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

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"

Sources

You can use the sources key to download an archive file from a public URL and unpack it in a target directory on the EC2 instance.

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) as long as the URL is publically accessible.

Example Snippet

The following example downloads a public .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 use the files key to download private files from Amazon S3 by providing an instance profile for authorization.

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

content

String content to add to the file. Specify either content or source, but not both.

source

URL of a file to download. Specify either content or source, but not both.

encoding

The encoding format of the string specified with the content option.

Valid values: plain | base64

group

Linux group that owns the file.

owner

Linux user that owns the 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 on the file.

authentication

The name of a AWS CloudFormation authentication method to use. You can add authentication methods to the autoscaling group metadata with the Resources key. See below for an example.

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"

The following example uses the Resources key to add an authentication method named S3Auth and uses it to download a private file from an Amazon S3 bucket:

Resources:
  AWSEBAutoScalingGroup:
    Metadata:
      AWS::CloudFormation::Authentication:
        S3Auth:
          type: "s3"
          buckets: ["elasticbeanstalk-us-west-2-123456789012"]
          roleName:
            "Fn::GetOptionSetting":
              Namespace: "aws:autoscaling:launchconfiguration"
              OptionName: "IamInstanceProfile"
              DefaultValue: "aws-elasticbeanstalk-ec2-role"

files:
  "/tmp/data.json" :
    mode: "000755"
    owner: root
    group: root
    authentication: "S3Auth"
    source: https://s3-us-west-2.amazonaws.com/elasticbeanstalk-us-west-2-123456789012/data.json

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.

By default, commands run in the root directory. To run commands from another directory, use the cwd option.

Syntax

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

Options

command

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. If not specified, commands run from the root directory (/).

test

(Optional) A command that must return the value true (exit code 0) in order for 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: "[ ! -x /usr/bin/python ]"

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, 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

ensureRunning

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

Set to false to ensure that the service is not running after 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 Elastic Beanstalk changes one directly via the files block, the service is restarted.

sources

A list of directories. If 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 Elastic Beanstalk installs or updates one of these packages, the service is restarted.

commands

A list of command names. If 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

Container Commands

You can use the container_commands key to execute commands that affect your application source code. Container commands run after the application and web server have been set up and the application version archive has been extracted, but before the application version is deployed. Non-container commands and other customization operations are performed prior to the application source code being extracted.

Container commands are run from the staging directory, where your source code is extracted prior to being deployed to the application server. Any changes you make to your source code in the staging directory with a container command will be included when the source is deployed to its final location.

You can use leader_only to only run the command on a single instance, or configure a test to only run the command when a test command evaluates to true. Leader-only container commands are only executed during environment creation and deployments, while other commands and server customization operations are performed every time an instance is provisioned or updated.

Syntax

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

Options

command

A string or array of strings to run.

env

(Optional) Set environment variables prior to running the command, overriding any existing value.

cwd

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

leader_only

(Optional) Only run the command on a single instance chosen by Elastic Beanstalk. Leader-only container commands are run before other container commands. A command can be leader-only or have a test, but not both (leader_only takes precedence).

test

(Optional) Run a test command that must return the true in order to run the container command. A command can be leader-only or have a test, but not both (leader_only takes precedence).

ignoreErrors

(Optional) Do not fail deployments if the container command returns a value other than 0 (success). Set to true to enable.

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"