The Java 8 / Jetty 9 Runtime

The Eclipse Jetty 9 runtime uses OpenJDK 8 and Jetty 9 with support for Java Servlet 3.1 Specification.

Note: The Jetty image inherits from the OpenJDK image and supports all of the configuration options described in The Java Runtime.

Prerequisites

• Download the latest version of the Google Cloud SDK or update your Cloud SDK to the current version:

  gcloud components update
  

• 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>1.3.2</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]

app.yaml

An app.yaml file is required. Define a file that looks like this:

flexible/helloworld/src/main/appengine/app.yaml

View on GitHub

runtime: java
env: flex

handlers:
- url: /.*
  script: this field is required, but ignored

The runtime image gcr.io/google-appengine/jetty is automatically selected when you deploy a WAR (*.war file).

If you want to use this image as a base for a custom runtime, you can specify runtime: custom in your app.yaml file and then write the Dockerfile like this:

FROM gcr.io/google-appengine/jetty
ADD your-application.war $APP_DESTINATION

These lines add the WAR in the correct location for the Docker container.

Other app.yaml settings are described in Using app.yaml.

pom.xml is for configuring Maven and build.gradle is for configuring Gradle.

Optional files

These configuration files are optional:

• index.yaml

• cron.yaml

• dispatch.yaml

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.

FROM launcher.gcr.io/google/jetty
ADD your-application.war $JETTY_BASE/webapps/root.war

# generate quickstart-web.xml
RUN /scripts/jetty/quickstart.sh

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 Stackdriver Logging (Beta)

When running on the App Engine flex environment, you can configure Java Util Logging to send logs to Google Stackdriver 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:

• Cloud Datastore

• Cloud PubSub

• Cloud Bigtable

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 SDK, run:

gcloud init

After completing the configurations, you can use the Google Cloud SDK 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 appengine:deploy

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 gcr.io/google-appengine/jetty. You can add additional directives to the Dockerfile to customize the Java runtime. See Building Custom Runtimes.

Your Dockerfile should begin like this:

FROM gcr.io/google-appengine/jetty
ADD your-application.war $APP_DESTINATION
# YOUR DOCKER COMMANDS

In this case, your-application.war is the name of the built WAR file in your target/ directory (maven), or build/staged-app/ (gradle).