The Java 8 / Jetty 9.3 Compat Runtime

The Java 8 / Jetty 9 Compat runtime uses Open JDK 8 and Jetty9 with Servlet 3.1. It is called "compatible" (or "compat") because it can be used to migrate an existing application from the App Engine standard environment to the flexible environment. It supports the same subset of App Engine standard environment APIs that are described in the migration page.

Before you begin

Before you start developing, follow these steps:

File organization

Your development file hierarchy should look like this:


Required files


If you are using the Maven Compiler Plugin, be sure that you have set the source and target values in the properties to compile Java 8 code:


  <properties>  <!-- App Engine Flex -->




    <!-- for hot reload of the web application -->

          <!-- dev appserver configuration (standard environment only) -->
          <!-- deploy configuration -->
<!--  defaults


Configure your app using an appengine-web.xml file. Your appengine-web.xml file should include the line:


Jetty 9 Quickstart works with advanced servlet annotations to improve startup performance. If you are using the Servlet 3.1 specification, and you want the Servlet 3.1 annotations to be processed, you must add these settings to your appengine-web.xml file:

  <setting name="java_quickstart" value="true"/>

This will cause the app to be scanned for annotations while it is being deployed or run locally, with the result being the same as if the equivalent elements had been included in the web.xml file.

Other appengine-web.xml settings are described in Using appengine-web.xml.

Optional files

The additional configuration files datastore-indexes.xml, cron.xml, and dispatch.xml are optional. They are placed in the WEB-INF directory. If they exist, they are automatically deployed each time you use the mvn appengine:deploy command.


The Dockerfile is optional. Include a Dockerfile if you want to customize the Java runtime.


The web.xml file is also optional. Use it only if you are not using Servlet 3.1 annotations.

Environment variables

In the Java 8 / Jetty 9 Compat runtime, you can also configure these optional environment variables.

Use the env-variables tag in the appengine-web.xml file to set environment variables. For example, to set the temporary directory:

  <env-var name="TMPDIR" value="/path/to/directory/" />

Testing your app

To test your app locally, use the command:

mvn appengine:run

Deploying your app

Use maven to deploy your app:

mvn appengine:deploy

If you are using any of the optional configuration files (index.yaml, cron.yaml, and dispatch.yaml) be sure to deploy them separately with the gcloud command, for example:

gcloud app deploy cron.yaml

Customizing the Java 8 / Jetty 9.3 compat runtime

If your app requires additional configuration, you can include a Dockerfile. The Dockerfile must be placed in the src/main/webapp directory as shown in Organizing your files. As shown below, the Dockerfile must include the base image and the ADD directive. The ADD directive includes your App Engine application in the image:

ADD .  /app/

Append any other Docker directives to this file to customize the runtime environment. Additional information can be found in Building Custom Runtimes.

Send feedback about...

App Engine flexible environment for Java docs