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

Create an Application Source Bundle

When you use the AWS Elastic Beanstalk console to deploy a new application or an application version, you'll need to upload 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 512 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 The Elastic Beanstalk Command Line Interface (EB CLI), Creating and Deploying Java Applications on AWS Elastic Beanstalk, and AWS Toolkit for Visual Studio.

Creating a Source Bundle for a .NET Application

We recommend that you 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.

  • It 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.

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.


To zip files in Mac OS X Finder

  1. Open your top-level project folder and select all the files and subfolders within it. Do not select the top-level folder itself.

    Files selected in Mac OS X Finder
  2. Right-click the selected files, and then choose Compress X items, where X is the number of files and subfolders you've selected.

    Compressing files in Mac OS X Finder

To zip files in Windows Explorer

  1. Open your top-level project folder and select all the files and subfolders within it. Do not select the top-level folder itself.

    Files selected in Windows Explorer
  2. Right-click the selected files, choose Send to, and then choose Compressed (zipped) folder.

    Compressing files in Windows Explorer

Creating a Source Bundle from the Command Line

When you create a source bundle using a zip command or jar command (Mac OS X or Linux), you might want to work in the same directory as your source files, rather than in a parent folder or other higher-level directory. This will help ensure that the file paths in the compressed archive do not include an extra parent folder. Mac OS X and Linux-based operating systems hide files and folders with names that begin with a period (.). The following command ensures that your source bundle includes folders that begin with a period, such as the .ebextensions folder.

Example

$ zip ../myapp.zip -r * .[^.]*
$ jar -cvf mywebapp.war *

Zipping files from the command line

Creating a Source Bundle with Git

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

To bundle your most recent Git commit

  • To create a ZIP archive of your most recent Git commit on the current branch, type the following command or issue it via a Git client, replacing <myapp> with your preferred archive name:

    $ git archive --format=zip HEAD > <myapp>.zip

    For more details, go to the git-archive manual page.

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.

To test the file extraction in Mac OS X or Linux

  1. Open a terminal window (Mac OS X) or connect to the Linux server. Navigate to the directory that contains your source bundle.

  2. Using the unzip or jar xf command, decompress the archive.

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

    Note

    If you use Mac OS X Finder to decompress the archive, a new top-level folder will be created, no matter how you structured the archive itself. For best results, use the command line.

To test the file extraction in Windows

  1. Download or install a program that allows you to extract compressed files via the command line. For example, you can download the free unzip.exe program from http://stahlforce.com/dev/index.php?tool=zipunzip.

  2. If necessary, copy the executable file to the directory that contains your source bundle. If you've installed a system-wide tool, you can skip this step.

  3. Using the appropriate command, decompress the archive. If you downloaded unzip.exe using the link in step 1, the command is unzip <archive-name>.

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