Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Webapp Runner CI Maven Central

Webapp Runner is designed to allow you to launch an exploded or compressed war that is on your filesystem into a tomcat container with a simple java -jar command. It currently supports Tomcat 9, older versions of webapp-runner for other Tomcat versions are no longer maintained.

Table of Contents


Webapp Runner is a standalone CLI tool that runs a WAR file. The simplest usage looks like this:

$ java -jar webapp-runner.jar path/to/project.war


You can use the Maven dependency plugin to download Webapp Runner as part of your build. This will eliminate the need for any external dependencies other than those specified in your build to run your application.


Now when you run maven package, Webapp Runner will be downloaded for you. You can then launch your application with:

$ java -jar target/dependency/webapp-runner.jar target/<appname>.war

Excluding Memcached and Redis libraries

Webapp Runner bundles Memcached and Redis client libraries into it's package. These libraries can cause conflicts with similar libraries in your application. This frequently manifests itself as a java.lang.NoSuchMethodError.

If you do not require these client libraries (because you are storing session data in some other way), you can exclude them by using webapp-runner-main instead of webapp-runner:


Store your sessions in Redis

Webapp Runner includes a session manager that stores sessions in redis.

To use it, add --session-store redis to your startup command:

$ java -jar webapp-runner.jar --session-store redis target/<appname>.war

The session store is configured via the following environment variables:


Store your sessions in memcache

Webapp Runner includes a session manager that stores sessions in memcache.

To use it, add --session-store memcache to your startup command:

$ java -jar webapp-runner.jar --session-store memcache target/<appname>.war

The session store is configured via the following environment variables:


Using behind a reverse proxy server

If you are using webapp-runner behind a proxy server, you can set the proxy base url within tomcat:

$ java -jar webapp-runner.jar --proxy-base-url target/<appname>.war

If you pass an HTTPS base url, e.g., secure flag will be automatically added to session cookies. This indicates to the browser that cookies should only be sent over a secure protocol.


Usage: <main class> [options]
      Enables AccessLogValue to STDOUT
      Default: false
      If --access-log is enabled, sets the logging pattern
      Default: common
      Password to be used with basic auth. Defaults to BASIC_AUTH_PW env
      Username to be used with basic auth. Defaults to BASIC_AUTH_USER env
      Controls when the socket used by the connector is bound. By default it
      is bound when the connector is initiated and unbound when the connector
      is destroyed., default value: true
      Default: true
      Comma delimited list of mime types that will be compressed when using
      GZIP compression.
      Default: text/html,text/xml,text/plain,text/css,application/json,application/xml,text/javascript,application/javascript
      The path to the context xml to use.
      Secure the app with basic auth. Use with --basic-auth-user and
      --basic-auth-pw or --tomcat-users-location
      Default: false
      Specify and in
      Default: false
      Enable GZIP compression on responses
      Default: false
      Enables JNDI naming
      Default: false
      Specify,, and in
      JAVA_OPTS. Note: should not be used if a reverse proxy is terminating
      SSL for you (such as on Heroku)
      Default: false
      Expand the war file and set it as source
      Default: true
      The name of the directory the WAR file will be expanded into.
      Default: expanded

      Set the maximum number of worker threads
      Default: 0
      The class name of the factory that creates the transcoder to use for
      serializing/deserializing sessions to/from memcached.
      The context path
      Default: <empty string>
      The port that the server will accept http requests on.
      Default: 8080
      Set proxy URL if tomcat is running behind reverse proxy
      Default: <empty string>
      Set jar scanner scan bootstrap classpath.
      Default: false
      Session store to use (valid options are 'memcache' or 'redis')
      Request pattern to not track sessions for. Valid only with memcache
      session store. (default is '.*\.(png|gif|jpg|css|js)$'. Has no effect
      for 'redis')
      Default: .*\.(png|gif|jpg|css|js)$
      Session locking mode for use with memcache session store. (default is
      all. Has no effect for 'redis')
      Default: all
      Operation timeout for the memcache session store. (default is 5000ms)
      Default: 5000
      Pool size of the session store connections (default is 10. Has no effect
      for 'memcache')
      Default: 10
      Enables or disables SSL endpoint identification for the redis session
      store. (default is true. Has no effect for 'memcache')
      Default: true
      The number of minutes of inactivity before a user's session is timed
      Overrides the default behavior and casues Tomcat to ignore lifecycle
      failure events rather than shutting down when they occur.
      Default: false
      Define the temp directory, default value: ./target/tomcat.PORT
      Location of the tomcat-users.xml file. (relative to the location of the
      webapp-runner jar file)
      Set the URI encoding to be used for the Connector.
      Set if the entity body encoding should be used for the URI.
      Default: false
      Set true to set ErrorReportValve properties showReport and showServerInfo to false. This protects from Apache stacktrace logging of malicious http requests. 
      Default: false
      Allows setting HTTP connector attributes. For example: -Acompression=on
      Syntax: -Akey=value
      Default: {}

See the Tomcat documentation for a complete list of HTTP connector attributes.


To run the entire suite of integration tests, use the following command:

$ ./mvnw clean install -Pintegration-test

To run an individual integration test, use a command like this:

$ ./mvnw clean install -Pintegration-test -Dinvoker.test=memcache-test