Using the Elastic Beanstalk Java SE platform - Amazon Elastic Beanstalk
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Using the Elastic Beanstalk Java SE platform

This topic describes how to configure, build, and run your Java applications that run on the Amazon Elastic Beanstalk Java SE platform.

The Elastic Beanstalk Java SE platform is a set of platform versions for Java web applications that can run on their own from a compiled JAR file. You can compile your application locally or upload the source code with a build script to compile it on-instance. Java SE platform versions are grouped into platform branches, each of which corresponds to a major version of Java.

Note

Elastic Beanstalk doesn't parse your application's JAR file. Keep files that Elastic Beanstalk needs outside of the JAR file. For example, include the cron.yaml file of a worker environment at the root of your application's source bundle, next to the JAR file.

Configuration options are available in the Elastic Beanstalk console for modifying the configuration of a running environment. To avoid losing your environment's configuration when you terminate it, you can use saved configurations to save your settings and later apply them to another environment.

To save settings in your source code, you can include configuration files. Settings in configuration files are applied every time you create an environment or deploy your application. You can also use configuration files to install packages, run scripts, and perform other instance customization operations during deployments.

The Elastic Beanstalk Java SE platform includes an nginx server that acts as a reverse proxy, serving cached static content and passing requests to your application. The platform provides configuration options to configure the proxy server to serve static assets from a folder in your source code to reduce the load on your application. For advanced scenarios, you can include your own .conf files in your source bundle to extend Elastic Beanstalk's proxy configuration or overwrite it completely.

If you only provide a single JAR file for your application source (on its own, not within a source bundle), Elastic Beanstalk renames your JAR file to application.jar, and then runs it using java -jar application.jar. To configure the processes that run on the server instances in your environment, include an optional Procfile in your source bundle. A Procfile is required if you have more than one JAR in your source bundle root, or if you want to customize the java command to set JVM options.

We recommend that you always provide a Procfile in the source bundle alongside your application. This way you precisely control which processes Elastic Beanstalk runs for your application and which arguments these processes receive.

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.

For details about the various ways you can extend an Elastic Beanstalk Linux-based platform, see Extending Elastic Beanstalk Linux platforms.

Configuring your Java SE environment

The Java SE platform settings let you fine-tune the behavior of your Amazon EC2 instances. You can edit the Elastic Beanstalk environment's Amazon EC2 instance configuration using the Elastic Beanstalk console.

Use the Elastic Beanstalk console to enable log rotation to Amazon S3 and configure variables that your application can read from the environment.

To configure your Java SE environment in the Elastic Beanstalk console
  1. Open the Elastic Beanstalk console, and in the Regions list, select your Amazon Web Services Region.

  2. In the navigation pane, choose Environments, and then choose the name of your environment from the list.

    Note

    If you have many environments, use the search bar to filter the environment list.

  3. In the navigation pane, choose Configuration.

  4. In the Updates, monitoring, and logging configuration category, choose Edit.

Log options

The Log Options section has two settings:

  • Instance profile – Specifies the instance profile that has permission to access the Amazon S3 bucket associated with your application.

  • Enable log file rotation to Amazon S3 – Specifies whether log files for your application's Amazon EC2 instances are copied to the Amazon S3 bucket associated with your application.

Static files

To improve performance, you can use the Static files section to configure the proxy server to serve static files (for example, HTML or images) from a set of directories inside your web application. For each directory, you set the virtual path to directory mapping. When the proxy server receives a request for a file under the specified path, it serves the file directly instead of routing the request to your application.

For details about configuring static files using configuration files or the Elastic Beanstalk console, see Serving static files.

Environment properties

The Environment Properties section lets you specify environment configuration settings on the Amazon EC2 instances that are running your application. Environment properties are passed in as key-value pairs to the application.

Inside the Java SE environment running in Elastic Beanstalk, environment variables are accessible using the System.getenv(). For example, you could read a property named API_ENDPOINT to a variable with the following code:

String endpoint = System.getenv("API_ENDPOINT");

See Environment properties and other software settings for more information.

Java SE configuration namespace

You can use a configuration file to set configuration options and perform other instance configuration tasks during deployments. Configuration options can be platform specific or apply to all platforms in the Elastic Beanstalk service as a whole. Configuration options are organized into namespaces.

The Java SE platform doesn't define any platform-specific namespaces. You can configure the proxy to serve static files by using the aws:elasticbeanstalk:environment:proxy:staticfiles namespace. For details and an example, see Serving static files.

Elastic Beanstalk provides many configuration options for customizing your environment. In addition to configuration files, you can also set configuration options using the console, saved configurations, the EB CLI, or the Amazon CLI. See Configuration options for more information.

If your Elastic Beanstalk Java SE environment uses an Amazon Linux AMI platform version (preceding Amazon Linux 2), read the additional information in this section.

Notes
  • The information in this topic only applies to platform branches based on Amazon Linux AMI (AL1). AL2023/AL2 platform branches are incompatible with previous Amazon Linux AMI (AL1) platform versions and require different configuration settings.

  • On July 18,2022, Elastic Beanstalk set the status of all platform branches based on Amazon Linux AMI (AL1) to retired. For more information about migrating to a current and fully supported Amazon Linux 2023 platform branch, see Migrating your Elastic Beanstalk Linux application to Amazon Linux 2023 or Amazon Linux 2.

You can use a configuration file to set configuration options and perform other instance configuration tasks during deployments. Configuration options can be platform specific or apply to all platforms in the Elastic Beanstalk service as a whole. Configuration options are organized into namespaces.

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:

option_settings: aws:elasticbeanstalk:container:java:staticfiles: /html: statichtml /images: staticimages

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.

Elastic Beanstalk provides many configuration options for customizing your environment. In addition to configuration files, you can also set configuration options using the console, saved configurations, the EB CLI, or the Amazon CLI. See Configuration options for more information.