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

Using the AWS Elastic Beanstalk Java SE Platform

You can use AWS Elastic Beanstalk to run, build, and configure Java web applications.


Elastic Beanstalk provides two Java SE configurations: Java 8 and Java 7. See supported platforms for details.

To configure the processes that run on the server instances in your environment, including Java virtual machine (JVM) container options like the amount of memory assigned to each, include an optional Procfile in your source bundle. A Procfile is required if you have more than one JAR in your source bundle root. If you only have one JAR file, Elastic Beanstalk will run it with java -jar application_name.jar.

To compile Java classes and run other build commands on the EC2 instances in your environment at deploy time, include a Buildfile in your application source bundle. A Buildfile lets you deploy your source code as-is and build on the server instead of compiling JARs locally. The Java SE platform includes common build tools to let you build on-server.

Elastic Beanstalk Java SE platform configurations include an nginx server that acts as a reverse proxy, serving cached static content and passing requests to your application.

The Java SE platform supports an extensible configuration option namespace that lets you define options that specify paths in an application that contains static files. This allows you to include a folder of static content in your source bundle and tell nginx to serve it directly to reduce load on your application.

Configuring the Application Process with a Procfile

If you have more than one JAR file in the root of your application source bundle, you must include a Procfile file that tells Elastic Beanstalk which JAR(s) to run. You can also include a Procfile file for a single JAR application to configure the Java virtual machine (JVM) that runs your application.

You must save the Procfile in your source bundle root. The file name is case sensitive. Format the Procfile as follows: a process name, followed by a colon, followed by a Java command that runs a JAR. Each line in your Procfile must match the following regular expression: ^[A-Za-z0-9_]+:\s*.+$.


web: java -jar server.jar -Xmms:256m
cache: java -jar mycache.jar
web_foo: java -jar other.jar

The command that runs the main JAR in your application must be called web, and it must be the first command listed in your Procfile. The nginx server forwards all HTTP requests that it receives from your environment's load balancer to this application.

By default, Elastic Beanstalk configures the nginx proxy to forward requests to your application on port 5000. You can override the default port by setting the PORT system property to the port on which your main application listens.


The port that your application listens on does not affect the port that the nginx server listens to receive requests from the load balancer.

If you use a Procfile to run multiple applications, Elastic Beanstalk expects each additional application to listen on a port 100 higher than the previous one. Elastic Beanstalk sets the PORT variable accessible from within each application to the port that it expects the application to run on. You can access this variable within your application code by calling System.getProperty("PORT").


In the preceding example, the web application listens on port 5000, cache listens on port 5100, and web_foo listens on port 5200. web configures its listening port by reading the PORT variable, and adds 100 to that number to determine which port cache is listening on so that it can send it requests.

Standard output and error streams from processes started with a Procfile are captured in log files named after the process and stored in /var/log. For example, the web process in the preceding example generates logs named web-1.log and web-1.error.log for stdout and stderr, respectively.

Elastic Beanstalk assumes that all entries in the Procfile should run at all times and automatically restarts any application defined in the Procfile that terminates. To run commands that will terminate and should not be restarted, use a Buildfile.

Building JARs On-Server with a Buildfile

You can build your application's class files and JAR(s) on the EC2 instances in your environment by invoking a build command from a Buildfile file in your source bundle.

A Buildfile file has the same syntax as a Procfile file, but commands in a Buildfile file are only run once and must terminate upon completion, whereas commands in a Procfile file are expected to run for the life of the application and will be restarted if they terminate. To run the JARs in your application, use a Procfile instead.

Add a file named Buildfile (case sensitive) to the root of your source bundle and configure it to invoke a build command in the following manner:


build: mvn assembly:assembly -DdescriptorId=jar-with-dependencies

The above example runs Apache Maven to build a web application from source code. Check out the Java web application samples for a sample application that uses this feature.

The Java SE platform includes the following build tools, which you can invoke from your build script:

  • javac – Java compiler

  • ant – Apache Ant

  • mvn – Apache Maven

  • gradle – Gradle

Execution Order

When you include multiple types of configuration in your application source bundle, they are executed in the following order. Each step does not begin until the previous step completes.

  • Step 1: commands, files and packages defined in configuration files (.ebextensions)

  • Step 2: Buildfile command

  • Step 3: container_commands in configuration files (.ebextensions)

  • Step 4: Procfile commands (all commands are run simultaneously)

For more information on using commands, files, packages and container_commands in configuration files, see Customizing Software on Linux Servers

Software Configuration Options

The Java SE platform supports one platform-specific configuration namespace in addition to the namespaces supported by all platforms. The aws:elasticbeanstalk:container:java:staticfiles namespace lets you define options that map paths on your web application to folders in your application source bundle that contain static content.

For example, this option_settings snippet defines two options in the static files namespace. The first maps the path /public to a folder named public, and the second maps the path /images to a folder named img:

  - namespace:  aws:elasticbeanstalk:container:java:staticfiles
    option_name:  /public
    value:  public
  - namespace:  aws:elasticbeanstalk:container:java:staticfiles
    option_name:  /images
    value:  img

The folders that you map using this namespace must be actual folders in the root of your source bundle. You cannot map a path to a folder in a JAR file.

No options are defined in this namespace by default.

Configuring the Reverse Proxy

Elastic Beanstalk uses nginx as the reverse proxy to map your application to your Elastic Load Balancing load balancer on port 80. Elastic Beanstalk provides a default nginx configuration that you can either extend or override completely with your own configuration.

To extend Elastic Beanstalk's default nginx configuration, add .conf configuration files to a folder named .ebextensions/nginx/conf.d/ in your application source bundle. Elastic Beanstalk's nginx configuration includes .conf files in this folder automatically.

|-- .ebextensions
|   `-- nginx
|       `-- conf.d
|           `-- myconf.conf
`-- web.jar

To override Elastic Beanstalk's default nginx configuration completely, include a configuration in your source bundle at .ebextensions/nginx/nginx.conf:

|-- .ebextensions
|   `-- nginx
|       `-- nginx.conf
`-- web.jar

If you override Elastic Beanstalk's nginx configuration, add the following line to your nginx.conf to pull in Elastic Beanstalk's configurations for Enhanced Health Reporting and Monitoring, automatic application mappings, and static files.

 include conf.d/elasticbeanstalk/*.conf;