Introduction

For AWS Elastic Beanstalk, .ebextensions does not belong inside the WAR itself. It must sit at the root of the application source bundle that you upload to Elastic Beanstalk, alongside the WAR file, so the platform can read the configuration before deploying the Java application.

Put .ebextensions In The Source Bundle Root

Elastic Beanstalk processes configuration files from a top-level directory named .ebextensions. If you package a Java application as a WAR, the usual deployment artifact is not just the bare WAR when you need custom environment configuration. Instead, you upload a ZIP source bundle that contains:

• the WAR file
• the .ebextensions directory
• optionally other deployment files such as platform hooks

A correct structure looks like this:

deployment-bundle.zip
|-- ROOT.war `-- .ebextensions |-- 01-nginx.config `-- 02-env.config ``` If you place `.ebextensions` inside the WAR archive, Elastic Beanstalk will not treat it as environment configuration. It will just be another directory inside your web application contents. ## Why The Location Matters Elastic Beanstalk evaluates `.ebextensions` while preparing the environment, not while Tomcat is reading your application archive. That is why the directory must be visible to the platform at the bundle root level. This distinction is easy to miss because a WAR is already a ZIP-like archive. But the platform lifecycle happens outside the webapp. Configuration needs to be available before the WAR is deployed. Typical uses for `.ebextensions` include: - setting environment options - writing configuration files - installing OS packages - running instance commands during deployment None of those tasks can work if the files are hidden inside the WAR where Elastic Beanstalk never scans for platform config. ## Example `.ebextensions` File Here is a small example that writes an application property on the instance: ```yaml files: "/opt/elasticbeanstalk/support/envvars.custom": mode: "000644" owner: root group: root content: |
      APP_MODE=production

Save that as something like .ebextensions/01-env.config in the bundle root, not in WEB-INF and not inside the WAR.

Packaging The Bundle

If your application must be deployed as a WAR and you also need .ebextensions, create a deployment ZIP that wraps both pieces together.

Example command sequence:

1mkdir deploy
2cp target/myapp.war deploy/ROOT.war
3cp -R .ebextensions deploy/.ebextensions
4cd deploy && zip -r ../deployment-bundle.zip .

That generated ZIP is what you upload to Elastic Beanstalk.

The exact WAR filename can vary by platform expectations and deployment style. Some Tomcat-based environments use ROOT.war to map the application to the root context.

Do Not Confuse App Files With Platform Files

A useful mental model is:

• WAR contents are for Tomcat and your Java application.
• '.ebextensions is for Elastic Beanstalk and the host environment.'

Once you separate those responsibilities, the packaging rule becomes obvious. The web server and the deployment platform are reading different layers of the bundle.

If you need application-level configuration, that belongs in the WAR. If you need environment-level deployment behavior, that belongs in .ebextensions at the bundle root.

Modern Alternatives

On newer Elastic Beanstalk platforms, you may also see .platform hooks used for certain customizations. That does not replace the location rule for .ebextensions; it just gives you another platform-level mechanism.

If your deployment setup is becoming complex, combining:

• a root-level .ebextensions
• optional .platform
• a clearly named WAR

is usually much easier to reason about than trying to hide everything inside the application archive.

Common Pitfalls

The most common mistake is placing .ebextensions inside the WAR file. Elastic Beanstalk will not process it there.

Another mistake is uploading only the WAR when the environment depends on custom config files. In that case the application may deploy, but instance setup steps will never run.

YAML formatting errors are also common. Even when the directory is in the right place, a malformed .config file can cause deployment failures or silently skipped behavior.

Finally, remember that .ebextensions belongs at the root of the uploaded source bundle, not one directory deeper inside a parent folder that was zipped by accident.

Summary

• '.ebextensions should be placed at the root of the Elastic Beanstalk source bundle.'
• Do not place it inside the WAR archive.
• When you need both a WAR and platform config, upload a ZIP bundle containing both.
• Use .ebextensions for environment setup and WAR contents for application code.
• Check both ZIP structure and YAML formatting if deployment behavior is missing.