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

Using the AWS Elastic Beanstalk Tomcat Platform

The AWS Elastic Beanstalk Tomcat platform is a set of environment configurations for Java web applications that can run in a Tomcat web container. Each configuration corresponds to a major version of Tomcat, including Java 8 with Tomcat 8 and Java 7 with Tomcat 7.

Platform-specific configuration options are available in the AWS Management 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.

Elastic Beanstalk Tomcat platform configurations include a reverse proxy that forwards requests to your application. The default server is Apache HTTP Server (version 2.2) but you can use configuration options to use nginx instead. Elastic Beanstalk also 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.

You must package Java applications in a web application archive (WAR) file with a specific structure. For information on the required structure and how it relates to the structure of your project directory, see Structuring your Project Folder.

To run multiple applications on the same web server, you can bundle multiple WAR files into a single source bundle. Each application in a multiple WAR source bundle runs at either the root path (ROOT.war runs at myapp.elasticbeanstalk.com/) or at a path directly beneath it (app2.war runs at myapp.elasticbeanstalk.com/app2/, as determined by the name of the WAR. In a single WAR source bundle, the application always runs at the root path.

Settings applied in the AWS Management Console override the same settings in configuration files, if they exist. This lets you have default settings in configuration files, and override them with environment specific settings in the console. For more information about precedence, and other methods of changing settings, see Configuration Options.

Configuring Your Tomcat Environment in the AWS Management Console

For Tomcat platform configurations on Elastic Beanstalk, Elastic Beanstalk provides a few platform-specific options in addition to the standard options it provides for all environments. These options let you configure the Java virtual machine (JVM) that runs on your environment's web servers, and define system properties that provide information configuration strings to your application.

You can use the AWS Management Console to enable log rotation to Amazon S3 and configure variables that your application can read from the environment.

To access the software configuration settings for your environment

  1. Open the Elastic Beanstalk console.

  2. Navigate to the management page for your environment.

  3. Choose Configuration.

  4. In the Software Configuration section, choose the settings icon ( Edit ).

JVM Container Options

The heap size in the Java virtual machine (JVM) determines how many objects your application can create in memory before garbage collection occurs. You can modify the Initial JVM Heap Size (-Xms argument) and a Maximum JVM Heap Size (-Xmx argument). A larger initial heap size allows more objects to be created before garbage collection occurs, but it also means that the garbage collector will take longer to compact the heap. The maximum heap size specifies the maximum amount of memory the JVM can allocate when expanding the heap during heavy activity.

Note

The available memory depends on the EC2 instance type. For more information about the EC2 instance types available for your Elastic Beanstalk environment, see Instance Types in the Amazon Elastic Compute Cloud User Guide for Linux.

The permanent generation is a section of the JVM heap that stores class definitions and associated metadata. To modify the size of the permanent generation, type the new size in the Maximum JVM PermGen Size (-XX:MaxPermSize argument) field. This setting only applies to Java 7 and earlier.

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 should be copied to your Amazon S3 bucket associated with your application.

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.

The Tomcat platform defines a placeholder property named JDBC_CONNECTION_STRING for Tomcat environments for passing a connection string to an external database.

Note

If you attach an RDS DB instance to your environment, construct the JDBC connection string dynamically from the RDS environment properties provided by Elastic Beanstalk. Use JDBC_CONNECTION_STRING only for database instances that are not provisioned using Elastic Beanstalk.

For more information about using Amazon Relational Database Service (Amazon RDS) with your Java application, see Adding an Amazon RDS DB Instance to Your Java Application Environment

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

String apiEndpoint = System.getProperty("API_ENDPOINT");

Configuration Files

You can use a configuration file to set configuration options and perform other instance configuration tasks during deployments.

The Tomcat platform supports options in the following namespaces in addition to the options supported for all Elastic Beanstalk environments:

  • aws:elasticbeanstalk:container:tomcat:jvmoptions – Modify JVM settings. Options in this namespace correspond to options in the management console as follows:

    • XmsJVM command line options

    • XmxJVM command line options

    • XX:MaxPermSizeMaximum JVM permanent generation size

    • JVM OptionsJVM command line options

  • aws:elasticbeanstalk:application:environment – Set environment properties.

  • aws:elasticbeanstalk:environment:proxy – Choose the proxy server and configure response compression.

  • aws:elasticbeanstalk:environment:proxy:staticfiles – Configure the proxy to serve static assets from a path in your source bundle.

The following example configuration file shows the use of the Tomcat-specific configuration options:

Example .ebextensions/tomcat-settings.config

option_settings:
  aws:elasticbeanstalk:container:tomcat:jvmoptions:
    Xms: 512m
    Xmx: 512m
    JVM Options: '-Xmn128m'
  aws:elasticbeanstalk:application:environment:
    API_ENDPOINT: mywebapi.zkpexsjtmd.us-west-2.elasticbeanstalk.com
  aws:elasticbeanstalk:environment:proxy:
    GzipCompression: 'true'
    ProxyServer: nginx
  aws:elasticbeanstalk:environment:proxy:staticfiles:
    /pub: public

See Java with Tomcat Platform Options for more information.

Configuring the Proxy Server

The Tomcat platform uses a reverse proxy to relay requests from port 80 on the instance to your Tomcat web container listening on port 8080. Elastic Beanstalk provides a default proxy configuration that you can either extend or override completely with your own configuration.

The Tomcat platform uses Apache 2.2 for the proxy by default. You can choose to use nginx by including a configuration file in your source code:

Example .ebextensions/nginx-proxy.config

option_settings:
  aws:elasticbeanstalk:environment:proxy:
    ProxyServer: nginx

Extending the Default Apache Configuration

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

~/workspace/my-app/
|-- .ebextensions
|   -- httpd
|      -- conf.d
|         -- myconf.conf
|         -- ssl.conf
-- index.jsp

For example, the following configuration adds a listener on port 5000:

Example .ebextensions/httpd/conf.d/port5000.conf

listen 5000
<VirtualHost *:5000>
  <Proxy *>
    Order Allow,Deny
    Allow from all
  </Proxy>
  ProxyPass / http://localhost:8080/ retry=0
  ProxyPassReverse / http://localhost:8080/
  ProxyPreserveHost on

  ErrorLog /var/log/httpd/elasticbeanstalk-error_log
</VirtualHost>

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

~/workspace/my-app/
|-- .ebextensions
|   `-- httpd
|       `-- conf
|           `-- httpd.conf
`-- index.jsp

If you override Elastic Beanstalk's Apache configuration, add the following lines to your httpd.conf to pull in Elastic Beanstalk's configurations for Enhanced Health Reporting and Monitoring, response compression, and static files.

Include conf.d/*.conf
Include conf.d/elasticbeanstalk/*.conf

Note

To override the default listener on port 80, include a file named 00_application.conf at .ebextensions/httpd/conf.d/elasticbeanstalk/ to overwrite Elastic Beanstalk's configuration.

Take a look at Elastic Beanstalk's default configuration file at /etc/httpd/conf/httpd.conf on an instance in your environment for a working example. All files in the .ebextensions/httpd folder in your source bundle are copied to /etc/httpd during deployments.

Extending the Default nginx 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.

~/workspace/my-app/
|-- .ebextensions
|   `-- nginx
|       `-- conf.d
|           |-- elasticbeanstalk
|           |   `-- my-server-conf.conf
|           `-- my-http-conf.conf
`-- index.jsp

Files with the .conf extension in the conf.d folder are included in the http block of the default configuration. Files in the conf.d/elasticbeanstalk folder are included in the server block within the http block.

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

~/workspace/my-app/
|-- .ebextensions
|   `-- nginx
|       `-- nginx.conf
`-- index.jsp

If you override Elastic Beanstalk's nginx configuration, add the following line to your configuration's server block to pull in Elastic Beanstalk's configurations for the port 80 listener, response compression, and static files.

 include conf.d/elasticbeanstalk/*.conf;

Note

To override the default listener on port 80, include a file named 00_application.conf at .ebextensions/nginx/conf.d/elasticbeanstalk/ to overwrite Elastic Beanstalk's configuration.

Also include the following line in your configuration's http block to pull in Elastic Beanstalk's configurations for Enhanced Health Reporting and Monitoring and logging.

    include       conf.d/*.conf;

Take a look at Elastic Beanstalk's default configuration file at /etc/nginx/nginx.conf on an instance in your environment for a working example. All files in the .ebextensions/nginx folder in your source bundle are copied to /etc/nginx during deployments.

Using .gitignore

To avoid committing compiled class files and WAR files to your Git repository, or seeing message about them appear when you run Git commands, add the relevant file types to a file named .gitignore in your project folder:

~/workspace/myapp/.gitignore

*.zip
*.class