Customizing software on Windows 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 or services that need to be run. For general information on customizing and configuring your Elastic Beanstalk environments, see Configuring Elastic Beanstalk environments.

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

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

Watch your environment's events while developing and testing configuration files. Elastic Beanstalk ignores a configuration file that contains validation errors, like an invalid key, and doesn't process any of the other keys in the same file. When this happens, Elastic Beanstalk adds a warning event to the event log.

Packages

Use the packages key to download and install prepackaged applications and components.

In Windows environments, Elastic Beanstalk supports downloading and installing MSI packages. (Linux environments support additional package managers. For details, see Packages on the Customizing Software on Linux Servers page.)

You can reference any external location, such as an Amazon Simple Storage Service (Amazon S3) object, as long as the URL is publicly accessible.

If you specify several msi: packages, their installation order isn't guaranteed.

Syntax

Specify a name of your choice as the package name, and a URL to an MSI file location as the value. You can specify multiple packages under the msi: key.

packages: 
  msi:
    package name: package url
    ...

Examples

The following example specifies a URL to download mysql from https://dev.mysql.com/.

packages:
  msi:
    mysql: https://dev.mysql.com/get/Downloads/Connector-Net/mysql-connector-net-8.0.11.msi

The following example specifies an Amazon S3 object as the MSI file location.

packages:
  msi:
    mymsi: https://amzn-s3-demo-bucket.s3.amazonaws.com/myobject.msi

Sources

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

In Windows environments, Elastic Beanstalk supports the .zip format. (Linux environments support additional formats. For details, see Sources on the Customizing Software on Linux Servers page.)

You can reference any external location, such as an Amazon Simple Storage Service (Amazon S3) object, as long as the URL is publicly accessible.

Example

The following example downloads a public .zip file from an Amazon S3 and unpacks it into c:/myproject/myapp.

sources:  
  "c:/myproject/myapp": https://amzn-s3-demo-bucket.s3.amazonaws.com/myobject.zip

Files

Use the files key to create files on the EC2 instance. The content can be either inline in the configuration file, or from a URL. The files are written to disk in lexicographic order. To download private files from Amazon S3, provide an instance profile for authorization.

Syntax

files:  
  "target file location on disk":
    source: URL
    authentication: authentication name:

  "target file location on disk":
    content: |
      this is my content
    encoding: encoding format

Options

Examples

The following example shows the two ways to provide file content: from a URL, or inline in the configuration file.

files:
  "c:\\targetdirectory\\targetfile.txt":
    source: http://foo.bar/myfile
 
  "c:/targetdirectory/targetfile.txt":
    content: |
      # this is my file
      # with content

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 :

files:
  "c:\\targetdirectory\\targetfile.zip":
    source: https://elasticbeanstalk-us-east-2-123456789012.s3.amazonaws.com/prefix/myfile.zip
    authentication: S3Auth

Resources:
  AWSEBAutoScalingGroup:
    Metadata:
      AWS::CloudFormation::Authentication:
        S3Auth:
          type: "s3"
          s: ["amzn-s3-demo-bucket"]
          roleName:
            "Fn::GetOptionSetting":
              Namespace: "aws:autoscaling:launchconfiguration"
              OptionName: "IamInstanceProfile"
              DefaultValue: "aws-elasticbeanstalk-ec2-role"

Commands

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.

The specified commands run as the Administrator user.

To troubleshoot issues with your commands, you can find their output in instance logs.

Syntax

commands:
  command name: 
    command: command to run

Options

Example

The following example saves the output of the set command to the specified file. If there is a subsequent command, Elastic Beanstalk runs that command immediately after this command completes. If this command requires a reboot, Elastic Beanstalk reboots the instance immediately after the command completes.

commands:
  test: 
    command: set > c:\\myapp\\set.txt
    waitAfterCompletion: 0

Services

Use the services key to define which services should be started or stopped when the instance is launched. The services key also enables 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: 
  windows:
    name of service:
      files:
        - "file name"
      sources: 
        - "directory"	
      packages: 
        name of package manager:
            "package name[: version]"
      commands: 
        - "name of command"

Options

Example

services: 
  windows:
    myservice:
      enabled: true
      ensureRunning: true

Container commands

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.

To troubleshoot issues with your container commands, you can find their output in instance logs.

Use the leader_only option 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. Leader-only container commands are not executed due to launch configuration changes, such as a change in the AMI Id or instance type.

Syntax

container_commands:
  name of container_command:
    command: command to run

Options

Example

The following example saves the output of the set command to the specified file. Elastic Beanstalk runs the command on one instance, and reboots the instance immediately after the command completes.

container_commands:
  foo:
    command: set > c:\\myapp\\set.txt
    leader_only: true
    waitAfterCompletion: 0