Configuring your Tomcat environment's proxy server - AWS Elastic Beanstalk

Configuring your Tomcat environment's proxy server

The Tomcat platform uses nginx (the default) or Apache HTTP Server as the 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 extend or override completely with your own configuration.

Configuring the proxy server on your platform version

All AL2023/AL2 platforms support a uniform proxy configuration feature. For more information about configuring the proxy server on your platform versions running AL2023/AL2, expand the Reverse Proxy Configuration section in Extending Elastic Beanstalk Linux platforms.

If your Elastic Beanstalk Tomcat 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.

Tomcat platform versions based on Amazon Linux AMI (preceding Amazon Linux 2) use Apache 2.4 for the proxy by default. You can choose to use Apache 2.2 or nginx by including a configuration file in your source code. The following example configures Elastic Beanstalk to use nginx.

Example .ebextensions/nginx-proxy.config
option_settings:
  aws:elasticbeanstalk:environment:proxy:
    ProxyServer: nginx

If your application was developed for Apache 2.2, read this section to learn about migrating to Apache 2.4.

Starting with Tomcat platform version 3.0.0 configurations, which were released with the Java with Tomcat platform update on May 24, 2018, Apache 2.4 is the default proxy of the Tomcat platform. The Apache 2.4 .conf files are mostly, but not entirely, backward compatible with those of Apache 2.2. Elastic Beanstalk includes default .conf files that work correctly with each Apache version. If your application doesn't customize Apache's configuration, as explained in Extending and overriding the default Apache configuration — Amazon Linux AMI (AL1), it should migrate to Apache 2.4 without any issues.

If your application extends or overrides Apache's configuration, you might have to make some changes to migrate to Apache 2.4. For more information, see Upgrading to 2.4 from 2.2 on The Apache Software Foundation's site. As a temporary measure, until you successfully migrate to Apache 2.4, you can choose to use Apache 2.2 with your application by including the following configuration file in your source code.

Example .ebextensions/apache-legacy-proxy.config
option_settings:
  aws:elasticbeanstalk:environment:proxy:
    ProxyServer: apache/2.2

For a quick fix, you can also select the proxy server in the Elastic Beanstalk console.

To select the proxy in your Tomcat environment in the Elastic Beanstalk console

  1. Open the Elastic Beanstalk console, and in the Regions list, select your AWS 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.

  5. For Proxy server, choose Apache 2.2 (deprecated).

  6. To save the changes choose Apply at the bottom of the page.

Choosing the proxy for a Tomcat environment in the Elastic Beanstalk console's software configuration category

You can extend the Elastic Beanstalk default Apache configuration with your additional configuration files. Alternatively, you can override the Elastic Beanstalk default Apache configuration completely.

Note

To extend the Elastic Beanstalk default Apache configuration, add .conf configuration files to a folder named .ebextensions/httpd/conf.d in your application source bundle. The Elastic Beanstalk 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 Apache 2.4 configuration adds a listener on port 5000.

Example .ebextensions/httpd/conf.d/port5000.conf
listen 5000
<VirtualHost *:5000>
  <Proxy *>
    Require all granted
  </Proxy>
  ProxyPass / http://localhost:8080/ retry=0
  ProxyPassReverse / http://localhost:8080/
  ProxyPreserveHost on

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

To override the Elastic Beanstalk 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 the Elastic Beanstalk Apache configuration, add the following lines to your httpd.conf to pull in the Elastic Beanstalk configurations for Elastic Beanstalk enhanced health reporting and monitoring, response compression, and static files.

IncludeOptional conf.d/*.conf
IncludeOptional conf.d/elasticbeanstalk/*.conf

If your environment uses Apache 2.2 as its proxy, replace the IncludeOptional directives with Include. For details about the behavior of these two directives in the two Apache versions, see Include in Apache 2.4, IncludeOptional in Apache 2.4, and Include in Apache 2.2.

Note

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

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

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. The Elastic Beanstalk 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 the Elastic Beanstalk 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
Notes

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

     include conf.d/elasticbeanstalk/*.conf;

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

  • Also include the following line in your configuration's http block to pull in the Elastic Beanstalk configurations for Elastic Beanstalk enhanced health reporting and monitoring and logging.

        include       conf.d/*.conf;

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