Google Cloud Platform Tomcat Runtime Image

This Project is Archived

This repository contains the source for the Google-maintained Tomcat docker image.

Using the Tomcat image

Running on App Engine Flexible

Cloud SDK

Simply choose the Java runtime with Tomcat as the server preference in app.yaml.

runtime: java
env: flex
runtime_config:
  server: tomcat8

Then you can deploy using the gcloud beta app deploy command. Note that the "beta" command is currently required.

Using custom Dockerfile

Specify a custom runtime in app.yaml.

runtime: custom
env: flex

Then create a Dockerfile that uses the Tomcat runtime image as specified in Other platforms.

Other platforms

Create a Dockerfile based on the image and add your application WAR:

FROM gcr.io/google-appengine/tomcat
COPY your-application.war $APP_DESTINATION_WAR

You can also use an exploded-war:

COPY your-application $APP_DESTINATION_EXPLODED_WAR

Configuring Tomcat

Tomcat properties

The Tomcat instance can be configured through the environment variable TOMCAT_PROPERTIES which is a comma-separated list of name=value pairs appended to catalina.properties.

Security best practices

Execute tomcat with a non-root user

For security purposes it is recommended to start the Tomcat instance using the tomcat user.

You can do so by adding USER tomcat at the end of your Dockerfile.

FROM gcr.io/google-appengine/tomcat
COPY your-application.war $APP_DESTINATION_WAR

RUN chown tomcat:tomcat $APP_DESTINATION_WAR
USER tomcat

If you are using an exploded-war, then use the $APP_DESTINATION_EXPLODED_WAR environment variable instead.

Optional Features

Distributed sessions

This image can be configured to store Tomcat sessions in the Google Cloud Datastore which allows multiple instances of Tomcat to share sessions.

You can enable this feature by adding distributed-sessions to the list of optional modules, which is specified in the TOMCAT_MODULES_ENABLE environment variable.

The distributed sessions module can be configured through the environment variable TOMCAT_PROPERTIES.

Property	Description	Default
gcp.distributed-sessions.namespace	Namespace to use in the Datastore.	tomcat-gcp-persistent-session
gcp.distributed-sessions.sessionKind	Name of the entity used to store sessions in the Datastore.	TomcatGCloudSession
gcp.distributed-sessions.uriExcludePattern	Pattern specifying which URI to ignore when persisting sessions.	null
gcp.distributed-sessions.enableTrace	Register the operations of the module in Stackdriver Trace. (The Trace module must also be active)	false

For example on Google App Engine:

env_variables:
  TOMCAT_MODULES_ENABLE: distributed-sessions
  TOMCAT_PROPERTIES: gcp.distributed-sessions.uriExcludePattern=^/_ah/.*

Usage outside of Google Cloud Platform

If you are using the runtime outside of GCP, you will want to make sure that your application has access to the Datastore. In this case, check out the Google Cloud Authentication guide.

Stackdriver Trace

The trace module sends information about requests (such as latency) to the Stackdriver Trace service.

To enable this module add stackdriver-trace to the list of enabled modules.

env_variables:
  TOMCAT_MODULES_ENABLE: stackdriver-trace

The following configuration is available through the the environment variable TOMCAT_PROPERTIES.

Property	Description	Default
gcp.stackdriver-trace.scheduledDelay	The traces are grouped before being sent to the Stackdriver service, this is the maximum time in seconds a trace can be buffered	15

Usage outside of Google Cloud Platform

When you are using this module outside of GCP you need to provide credentials through Google Cloud Authentication.

Stackdriver Logging

When the Tomcat runtime is running on Google App Engine flexible environment all output to stdout/stderr is forwarded to Stackdriver Logging and available in the Cloud Console Log Viewer.

However more detailed and integrated logs are available if the Stackdriver Logging mechanism is used directly.

To take advantage of this integration, add the Google Cloud Java Client for Logging to your dependencies and provide a Java Util Logging configuration file (logging.properties) as part of the resources of the application (classes/logging.properties) with the following content:

handlers=com.google.cloud.logging.LoggingHandler

# Optional configuration
.level=FINE
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

Enabling gzip compression

Tomcat offers the possibility to use GZIP compression.

To take advantage of this feature set the property tomcat.server.connector.compression to on:

env_variables:
  TOMCAT_PROPERTIES: tomcat.server.connector.compression=on

You can also specify a numerical value indicating the minimal amount of data (in bytes) before using compression.

Detailed documentation can be found in the Tomcat documentation, at the attribute compression.

Development Guide

• See instructions on how to build and test this image.

Contributing changes

• See CONTRIBUTING.md

Licensing

• See LICENSE