The Java runtime is the software stack responsible for installing your application code and dependencies, and then running that application in the flexible environment.
Version
11
and later are built using buildpacks, which requires you to choose an operating system in yourapp.yaml
file. For example, to use Java 21, you must specify Ubuntu 22 as the operating system.The Java 8 / Jetty 9 runtime provides OpenJDK 8 and Eclipse Jetty 9 with support for the Java Servlet 3.1 Specification. The Jetty image inherits from the OpenJDK image.
For the full list of supported Java versions, and their corresponding Ubuntu version, see the Runtime support schedule.
Prerequisites
To use the Java runtime:
You must install gcloud CLI version 420.0.0 or later. You can update your CLI tooling by running the
gcloud components update
command. To view your installed version, you can run thegcloud version
command.To deploy using Maven, you will need to add the App Engine Maven Plugin to your
pom.xml
:<plugin> <groupId>com.google.cloud.tools</groupId> <artifactId>appengine-maven-plugin</artifactId> <version>2.7.0</version> </plugin>
Other options for deploying include the
gcloud app deploy
command or the App Engine Gradle plugin.
Organizing your files
Your source tree should look like this:
MyDir/ [pom.xml] [build.gradle] [index.yaml] [cron.yaml] [dispatch.yaml] src/main/ appengine/ app.yaml docker/ [Dockerfile] java/ com.example.mycode/ MyCode.java webapp/ [index.html] [jsp.jsp] WEB-INF/ [web.xml]
Choose a Java version
New runtime versions
For Java runtime version 11 and later, you must include the
runtime_config
and operating_system
settings in your
app.yaml
file to specify
an operating system.
Optionally, you can specify a runtime version by including the runtime_version
setting in your app.yaml
file. By default, the latest Java version is used if
the runtime_version
setting is not specified.
Examples
To specify Java 21 on Ubuntu 22:
runtime: java env: flex runtime_config: operating_system: "ubuntu22" runtime_version: "21"
To specify the latest supported Java version on Ubuntu 22:
runtime: java env: flex runtime_config: operating_system: "ubuntu22"
Previous runtime versions
For Java 8, specify runtime_config
and jdk
settings in your
app.yaml
file.
Java 8 supports:
- The Eclipse Jetty 9 runtime and runs Jetty 9 using Servlet 3.1.
- Your own server code that listens on port 8080 as part of your application. This feature enables you to use microservice frameworks like SparkJava and Spring-Boot.
Examples
Specifying Jetty version 9 (default / optional):
runtime_config: jdk: openjdk8 server: jetty9
Specifying Java version 8:
runtime_config: jdk: openjdk8
Sample
app.yaml
for Java 8:
See pom.xml
for configuring Maven and build.gradle
for configuring Gradle.
Optional files
These configuration files are optional:
Place these files at the top level of MyDir. If you use any these files, you
must deploy them separately with the gcloud app deploy
command.
web.xml
is optional and only needed if you are not using Servlet 3.x annotations.
You can place static web content, as well as your JavaServer pages, in your
webapp/
directory.
Jetty 9, which the App
Engine flexible environment uses as its Servlet container, uses
Apache Jasper
as the default JSP implementation and includes JSTL taglibs.
The Dockerfile file is optional and used to customize the Java runtime.
Enabling gzip compression
The gzip
handler is bundled with Jetty but not activated by default. To
activate this module, set the environment variable, JETTY_MODULES_ENABLE=gzip
,
in the app.yaml
file:
env_variables:
JETTY_MODULES_ENABLE: 'gzip'
Using Quickstart
Jetty
can speed up
the start time of your application by pre-scanning its content and generating
configuration files.
If you are using an
extended image
you can activate quickstart by executing /scripts/jetty/quickstart.sh
in your
Dockerfile, after the application WAR is added.
Environment variables
You can set the following optional environment variables that are specific to the Java 8/Jetty 9 runtime. You can set OpenJDK 8 environment variables as well.
To set environment variables, use the env_variables
key in the app.yaml
file.
Env Var | Maven Prop | Value/Comment |
---|---|---|
JETTY_PROPERTIES |
Comma separated list of name=value pairs appended to $JETTY_ARGS |
|
JETTY_MODULES_ENABLE |
Comma separated list of modules to enable by appending to $JETTY_ARGS |
|
JETTY_MODULES_DISABLE |
Comma separated list of modules to disable by removing from $JETTY_BASE/start.d |
|
JETTY_ARGS |
Arguments passed to jetty's start.jar . Any arguments used for custom jetty configuration should be passed here. |
|
JAVA_OPTS |
JVM runtime arguments |
Enhanced Cloud Logging (Beta)
When running on the App Engine flex environment, you can configure Java Util
Logging to send logs to Cloud Logging by setting the
JETTY_ARGS
environment variable. For example:
env_variables:
JETTY_ARGS: -Djava.util.logging.config.file=WEB-INF/logging.properties
You must provide a logging.properties file that configures a LoggingHandler as follows:
handlers=com.google.cloud.logging.LoggingHandler
# Optional configuration
.level=INFO
com.google.cloud.logging.LoggingHandler.level=FINE
com.google.cloud.logging.LoggingHandler.log=gae_app.log
com.google.cloud.logging.LoggingHandler.formatter=java.util.logging.SimpleFormatter
java.util.logging.SimpleFormatter.format=%3$s: %5$s%6$s
Local testing
When testing in your local environment, you may use emulated Google Cloud services, rather than remote Google Cloud services. You can use the following emulators:
Use the gcloud
command to start them before you run your app:
gcloud beta emulators datastore start
gcloud beta emulators pubsub start
gcloud beta emulators bigtable start
Maven
Add these lines in your maven pom.xml
file to add the
Jetty 9 Maven Plugin:
<plugin>
<groupId>org.eclipse.jetty</groupId>
<artifactId>jetty-maven-plugin</artifactId>
<version>9.4.2.v20170220</version>
</plugin>
To run your app locally, use the Maven command:
mvn jetty:run-exploded
Gradle
Follow the
Creating a new Gradle project
instructions to add the
Gretty Gradle plugin
to your build.gradle
, and use the command:
gradle jettyRun
Deploying your app
To initialize the Google Cloud CLI, run:
gcloud init
After completing the configurations, you can use the Google Cloud CLI to deploy
this directory containing the app.yaml
and WAR files using:
gcloud app deploy app.yaml
If you are using any of the optional configuration files (index.yaml
,
cron.yaml
, and dispatch.yaml
) deploy them separately with the gcloud
command. For example:
gcloud app deploy cron.yaml
Maven
Use Maven to deploy your app:
mvn package appengine:deploy -Dapp.deploy.projectId=PROJECT_ID
Replace PROJECT_ID with the ID of your Google Cloud project. If
your pom.xml
file already
specifies your
project ID, you don't need to include the -Dapp.deploy.projectId
property in the
command you run.
Gradle
Use Gradle to deploy your app:
gradle appengineDeploy
Customizing the Java 8 / Jetty 9 runtime
You don't need a Dockerfile to deploy your app into the Java 8/Jetty 9 runtime. If your app requires additional configuration, you can explicitly provide a Dockerfile to customize the Java runtime. The Dockerfile must include the base image. You can add additional directives to the Dockerfile to customize the Java runtime. See Building custom runtimes.
In this case, your-application.war
is the name of the built WAR file
in your target/
directory (maven), or build/staged-app/
(gradle).