Create an Elastic Beanstalk application source bundle

This topic explains how to upload your application source files to Elastic Beanstalk in a source bundle. It explains the requirements of a source bundle, the structure, and the approaches to create one.

When you use the AWS Elastic Beanstalk console to deploy a new application or an application version, you'll need to upload the files for the application in a source bundle. Your source bundle must meet the following requirements:

• Consist of a single ZIP file or WAR file (you can include multiple WAR files inside your ZIP file)

• Not exceed 500 MB

• Not include a parent folder or top-level directory (subdirectories are fine)

If you want to deploy a worker application that processes periodic background tasks, your application source bundle must also include a cron.yaml file. For more information, see Periodic tasks.

If you are deploying your application with the Elastic Beanstalk Command Line Interface (EB CLI), the AWS Toolkit for Eclipse, or the AWS Toolkit for Visual Studio, the ZIP or WAR file will automatically be structured correctly. For more information, see Using the Elastic Beanstalk command line interface (EB CLI), Deploying Java applications with Elastic Beanstalk, and The AWS Toolkit for Visual Studio.

Creating a source bundle from the command line

Create a source bundle using the zip command. To include hidden files and folders, use a pattern like the following.

~/myapp$ zip ../myapp.zip -r * .[^.]*
  adding: app.js (deflated 63%)
  adding: index.js (deflated 44%)
  adding: manual.js (deflated 64%)
  adding: package.json (deflated 40%)
  adding: restify.js (deflated 85%)
  adding: .ebextensions/ (stored 0%)
  adding: .ebextensions/xray.config (stored 0%)

This ensures that Elastic Beanstalk configuration files and other files and folders that start with a period are included in the archive.

For Tomcat web applications, use jar to create a web archive.

~/myapp$ jar -cvf myapp.war .

The above commands include hidden files that may increase your source bundle size unnecessarily. For more control, use a more detailed file pattern, or create your source bundle with Git.

Creating a source bundle with Git

If you're using Git to manage your application source code, use the git archive command to create your source bundle.

$ git archive -v -o myapp.zip --format=zip HEAD

git archive only includes files that are stored in git, and excludes ignored files and git files. This helps keep your source bundle as small as possible. For more information, go to the git-archive manual page.

Zipping files in Mac OS X Finder or Windows explorer

When you create a ZIP file in Mac OS X Finder or Windows Explorer, make sure you zip the files and subfolders themselves, rather than zipping the parent folder.

Note

The graphical user interface (GUI) on Mac OS X and Linux-based operating systems does not display files and folders with names that begin with a period (.). Use the command line instead of the GUI to compress your application if the ZIP file must include a hidden folder, such as .ebextensions. For command line procedures to create a ZIP file on Mac OS X or a Linux-based operating system, see Creating a source bundle from the command line.

Example

Suppose you have a Python project folder labeled myapp, which includes the following files and subfolders:

myapplication.py
README.md
static/
static/css
static/css/styles.css
static/img
static/img/favicon.ico
static/img/logo.png
templates/
templates/base.html
templates/index.html

As noted in the list of requirements above, your source bundle must be compressed without a parent folder, so that its decompressed structure does not include an extra top-level directory. In this example, no myapp folder should be created when the files are decompressed (or, at the command line, no myapp segment should be added to the file paths).

This sample file structure is used throughout this topic to illustrate how to zip files.

Creating a source bundle for a .NET application

If you use Visual Studio, you can use the deployment tool included in the AWS Toolkit for Visual Studio to deploy your .NET application to Elastic Beanstalk. For more information, see Deploying Elastic Beanstalk applications in .NET using the deployment tool.

If you need to manually create a source bundle for your .NET application, you cannot simply create a ZIP file that contains the project directory. You must create a web deployment package for your project that is suitable for deployment to Elastic Beanstalk. There are several methods you can use to create a deployment package:

• Create the deployment package using the Publish Web wizard in Visual Studio. For more information, go to How to: Create a Web Deployment Package in Visual Studio.

  Important

  When creating the web deployment package, you must start the Site name with Default Web Site.

• If you have a .NET project, you can create the deployment package using the msbuild command as shown in the following example.

  Important

  The DeployIisAppPath parameter must begin with Default Web Site.

  C:/> msbuild <web_app>.csproj /t:Package /p:DeployIisAppPath="Default Web Site"

• If you have a website project, you can use the IIS Web Deploy tool to create the deployment package. For more information, go to Packaging and Restoring a Web site.

  Important

  The apphostconfig parameter must begin with Default Web Site.

If you are deploying multiple applications or an ASP.NET Core application, put your .ebextensions folder in the root of the source bundle, side by side with the application bundles and manifest file:

~/workspace/source-bundle/
|-- .ebextensions
|   |-- environmentvariables.config
|   `-- healthcheckurl.config
|-- AspNetCore101HelloWorld.zip
|-- AspNetCoreHelloWorld.zip
|-- aws-windows-deployment-manifest.json
`-- VS2015AspNetWebApiApp.zip

Testing your source bundle

You may want to test your source bundle locally before you upload it to Elastic Beanstalk. Because Elastic Beanstalk essentially uses the command line to extract the files, it's best to do your tests from the command line rather than with a GUI tool.

Ensure that the decompressed files appear in the same folder as the archive itself, rather than in a new top-level folder or directory.