• Stars
    star
    319
  • Rank 131,491 (Top 3 %)
  • Language
    Java
  • License
    BSD 3-Clause "New...
  • Created almost 13 years ago
  • Updated about 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Lightweight Application Launcher. Launch your webapp in the most popular open source web container available with a single command.

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

Usage

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

Maven

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.

<plugins>
  <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-dependency-plugin</artifactId>
      <version>3.3.0</version>
      <executions>
          <execution>
              <phase>package</phase>
              <goals>
                  <goal>copy</goal>
              </goals>
              <configuration>
                  <artifactItems>
                      <artifactItem>
                          <groupId>com.github.heroku</groupId>
                          <artifactId>webapp-runner</artifactId>
                          <version>${webapp-runner.version}</version>
                          <destFileName>webapp-runner.jar</destFileName>
                      </artifactItem>
                  </artifactItems>
              </configuration>
          </execution>
      </executions>
  </plugin>
</plugins>

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:

<artifactItem>
    <groupId>com.github.heroku</groupId>
    <artifactId>webapp-runner-main</artifactId>
    <version>${webapp-runner.version}</version>
    <destFileName>webapp-runner.jar</destFileName>
</artifactItem>

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:

  • REDIS_URL

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:

  • MEMCACHE_SERVERS
  • MEMCACHE_USERNAME
  • MEMCACHE_PASSWORD

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 https://example.com target/<appname>.war

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

Options

Usage: <main class> [options]
  Options:
    --access-log
      Enables AccessLogValue to STDOUT
      Default: false
    --access-log-pattern
      If --access-log is enabled, sets the logging pattern
      Default: common
    --basic-auth-pw
      Password to be used with basic auth. Defaults to BASIC_AUTH_PW env
      variable.
    --basic-auth-user
      Username to be used with basic auth. Defaults to BASIC_AUTH_USER env
      variable.
    --bind-on-init
      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
    --compressable-mime-types
      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
    --context-xml
      The path to the context xml to use.
    --enable-basic-auth
      Secure the app with basic auth. Use with --basic-auth-user and
      --basic-auth-pw or --tomcat-users-location
      Default: false
    --enable-client-auth
      Specify -Djavax.net.ssl.keyStore and -Djavax.net.ssl.keyStorePassword in
      JAVA_OPTS
      Default: false
    --enable-compression
      Enable GZIP compression on responses
      Default: false
    --enable-naming
      Enables JNDI naming
      Default: false
    --enable-ssl
      Specify -Djavax.net.ssl.keyStore, -Djavax.net.ssl.keystoreStorePassword,
      -Djavax.net.ssl.trustStore and -Djavax.net.ssl.trustStorePassword in
      JAVA_OPTS. Note: should not be used if a reverse proxy is terminating
      SSL for you (such as on Heroku)
      Default: false
    --expand-war-file
      Expand the war file and set it as source
      Default: true
    --expanded-dir-name
      The name of the directory the WAR file will be expanded into.
      Default: expanded
    --help

    --max-threads
      Set the maximum number of worker threads
      Default: 0
    --memcached-transcoder-factory-class
      The class name of the factory that creates the transcoder to use for
      serializing/deserializing sessions to/from memcached.
    --path
      The context path
      Default: <empty string>
    --port
      The port that the server will accept http requests on.
      Default: 8080
    --proxy-base-url
      Set proxy URL if tomcat is running behind reverse proxy
      Default: <empty string>
    --scanBootstrapClassPath
      Set jar scanner scan bootstrap classpath.
      Default: false
    --session-store
      Session store to use (valid options are 'memcache' or 'redis')
    --session-store-ignore-pattern
      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-store-locking-mode
      Session locking mode for use with memcache session store. (default is
      all. Has no effect for 'redis')
      Default: all
    --session-store-operation-timeout
      Operation timeout for the memcache session store. (default is 5000ms)
      Default: 5000
    --session-store-pool-size
      Pool size of the session store connections (default is 10. Has no effect
      for 'memcache')
      Default: 10
    --session-store-ssl-endpoint-identification
      Enables or disables SSL endpoint identification for the redis session
      store. (default is true. Has no effect for 'memcache')
      Default: true
    --session-timeout
      The number of minutes of inactivity before a user's session is timed
      out.
    --shutdown-override
      Overrides the default behavior and casues Tomcat to ignore lifecycle
      failure events rather than shutting down when they occur.
      Default: false
    --temp-directory
      Define the temp directory, default value: ./target/tomcat.PORT
    --tomcat-users-location
      Location of the tomcat-users.xml file. (relative to the location of the
      webapp-runner jar file)
    --uri-encoding
      Set the URI encoding to be used for the Connector.
    --use-body-encoding-for-uri
      Set if the entity body encoding should be used for the URI.
      Default: false
    --secure-error-report-valve
      Set true to set ErrorReportValve properties showReport and showServerInfo to false. This protects from Apache stacktrace logging of malicious http requests. 
      Default: false
    -A
      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.

Development

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

More Repositories

1

react-refetch

A simple, declarative, and composable way to fetch data for React components
JavaScript
3,439
star
2

legacy-cli

Heroku CLI
Ruby
1,370
star
3

heroku-pg-extras

A heroku plugin for awesome pg:* commands that are also great and fun and super.
JavaScript
1,306
star
4

heroku-buildpack-nodejs

The official Heroku buildpack for Node.js apps.
Shell
1,265
star
5

node-js-getting-started

Getting Started with Node on Heroku
EJS
1,054
star
6

logplex

[DEPRECATED] Heroku log router
Erlang
984
star
7

heroku-buildpack-python

The official Heroku buildpack for Python apps
Ruby
953
star
8

heroku-django-template

A Django 2.0 base template featuring all recommended best practices for deployment on Heroku and local development.
Python
901
star
9

node-js-sample

This repository is deprecated. Head over to https://github.com/heroku/node-js-getting-started
JavaScript
847
star
10

cli

Heroku CLI
JavaScript
847
star
11

rails_12factor

Ruby
845
star
12

python-getting-started

Getting Started with Python on Heroku.
Python
818
star
13

heroku-buildpack-php

The official PHP buildpack for Heroku.
Shell
799
star
14

heroku-buildpack-go

Heroku Go Buildpack
Shell
790
star
15

heroku-buildpack-ruby

Heroku's Ruby Buildpack
Ruby
778
star
16

hk

DEPRECATED: see
Go
709
star
17

heroku-buildpack-static

[DEPRECATED] Heroku buildpack for handling static sites and single page web apps
Ruby
681
star
18

heroku-repo

Plugin for heroku CLI that can manipulate the repo
JavaScript
680
star
19

vegur

Vegur: HTTP Proxy Library
Erlang
620
star
20

heroku-accounts

Helps use multiple accounts on Heroku.
JavaScript
548
star
21

django-heroku

[DEPRECATED] Do not use! See https://github.com/heroku/django-heroku/issues/56
Python
465
star
22

heroku-buildpack-pgbouncer

Run pgbouncer in a dyno along with your application
Shell
335
star
23

devcenter-embedded-tomcat

Java
330
star
24

docker-registry-client

A Go API client for the v2 Docker Registry API
Go
287
star
25

heroku-buildpack-google-chrome

Run (headless) Google Chrome on Heroku
Shell
283
star
26

stack-images

Recipies for building Heroku's stack images
Shell
264
star
27

java-getting-started

Getting Started with Java on Heroku
HTML
248
star
28

identity

[DEPRECATED] Login and OAuth management service for Heroku
CSS
247
star
29

go-getting-started

Getting Started with Go on Heroku https://devcenter.heroku.com/articles/getting-started-with-go
Dockerfile
246
star
30

heroku-buildpack-nginx

Run NGINX in a Heroku app
Shell
242
star
31

heroku-buildpack-apt

Buildpack that installs APT based dependencies
Shell
239
star
32

log-shuttle

HTTP log transport.
Go
236
star
33

terrier

Terrier is a Image and Container analysis tool that can be used to scan Images and Containers to identify and verify the presence of specific files according to their hashes.
Go
227
star
34

umpire

HTTP metrics monitoring endpoint
Ruby
221
star
35

platform-api

Ruby HTTP client for the Heroku API
Ruby
211
star
36

starboard

onboarding, offboarding, or crossboarding made easy
SCSS
204
star
37

salesforce-bulk

Python interface to the Salesforce.com Bulk API
Python
203
star
38

php-getting-started

Getting Started with PHP on Heroku
Twig
200
star
39

heroku-container-tools

DEPRECATED Heroku Toolbelt plugin to help configure, test and release apps to Heroku using local containers.
JavaScript
195
star
40

heroku-buildpack-scala

Heroku buildpack: Scala
Shell
190
star
41

node-heroku-client

A wrapper around the Heroku API for Node.js
JavaScript
188
star
42

vulcan

A build server in the cloud.
Ruby
172
star
43

pg_lock

Use Postgres advisory lock to isolate code execution across machines
Ruby
168
star
44

awsdetailedbilling

A toolkit for importing AWS detailed billing reports into Redshift
JavaScript
167
star
45

heroku-buildpack-java

A Heroku buildpack for Java apps.
Shell
167
star
46

pulse

DEPRECATED: Real-time Heroku operations dashboard
Clojure
161
star
47

heroku.rb

DEPRECATED! Official Heroku Ruby Legacy API wrapper
Ruby
161
star
48

heroku-buildpack-multi

[DEPRECATED] Please use https://devcenter.heroku.com/articles/using-multiple-buildpacks-for-an-app instead
Shell
157
star
49

erlang-in-anger

A little guide about how to be the Erlang medic in a time of war. It is first and foremost a collection of tips and tricks to help understand where failures come from, and a dictionary of different code snippets and practices that helped developers debug production systems that were built in Erlang.
TeX
157
star
50

plexy

A toolkit for building excellent APIs with Elixir
Elixir
154
star
51

heroku-buildpack-multi-procfile

Everyone gets a Procfile!
Shell
150
star
52

log2viz

DEFUNCT: Realtime analysis of your Heroku app logs.
Ruby
145
star
53

heroku.py

DEPRECATED! Heroku API wrapper for Python.
Python
142
star
54

facebook-template-nodejs

JavaScript
136
star
55

ruby-getting-started

Getting Started with Ruby on Heroku
Ruby
120
star
56

heroku-buildpack-chromedriver

Installs chromedriver in a Heroku slug
Shell
117
star
57

heroku-buildpack-clojure

Heroku's buildpack for Clojure applications.
Shell
115
star
58

mobile-template1

JavaScript
115
star
59

instruments

Collecting metrics over discrete time intervals
Go
112
star
60

heroku-sbt-plugin

An sbt plugin for deploying Heroku Scala applications
Scala
111
star
61

heroku-buildpack-erlang

Erlang buildpack
Shell
107
star
62

terraform-provider-heroku

Terraform Heroku provider
Go
99
star
63

cli-engine

TypeScript
97
star
64

semver.io

*DEPRECATED* The semver.io instance has now been sunset: https://github.com/heroku/semver.io/issues/74
CoffeeScript
96
star
65

facebook-template-php

example facebook app for heroku
PHP
96
star
66

dotnet-buildpack

ASP.NET 5 Buildpack
Shell
92
star
67

kensa

A tool to help Heroku add-on providers integrate their services with Heroku
Ruby
92
star
68

netrc

Reads and writes netrc files.
Ruby
89
star
69

hstore_example

Ruby
89
star
70

alpinehelloworld

An Alpine-based Docker example
Python
85
star
71

heroku-kong

๐Ÿ’ Kong API gateway as a Heroku app
Lua
84
star
72

heroku-buildpack-hello

Shell
82
star
73

heroku-releases-retry

CLI plugin to allow retrying the latest release-phase command
JavaScript
79
star
74

faceplate

A Node.js wrapper for Facebook authentication and API
JavaScript
76
star
75

rails_stdout_logging

Logs to stdout so you don't have to
Ruby
76
star
76

shaas

Shell as a Service: API to inspect and execute scripts in a server's environment via HTTP and WebSockets
Go
75
star
77

devcenter-spring-mvc-hibernate

AspectJ
75
star
78

heroku-buildpack-core-data

A Heroku Buildpack that generates a REST webservice from a Core Data model
Shell
74
star
79

heroku-buildpack-emberjs

**This buildpack is deprecated!** Please use the official Node.js buildpack combined with the static or nginx buildpack instead.
Ruby
72
star
80

facebook-template-python

Python
69
star
81

devcenter-java

Java
62
star
82

heroku-buildpack-c

C Language Pack
Shell
62
star
83

nibs

JavaScript
61
star
84

heroku-buildpack-gradle

This is a Heroku buildpack for Gradle apps. It uses Gradle to build your application and OpenJDK to run it.
Shell
61
star
85

heroku-buildpack-ember-cli

A Heroku buildpack for ember-cli apps; powers dashboard.heroku.com
Shell
60
star
86

heroku-guardian

Easy to use CLI security checks for the Heroku platform. Validate baseline security configurations for your own Heroku deployments.
Python
60
star
87

cnb-builder-images

Recipes for building Heroku's Cloud Native Buildpacks builder images
Java
59
star
88

list-of-ingredients

An example of using Create React App with Rails 5 API and ActiveAdmin on Heroku
Ruby
57
star
89

heroku-fork

Heroku CLI plugin to fork an existing app into a new app
JavaScript
55
star
90

salesforce-buildpack

Heroku Buildpack for Salesforce
Shell
53
star
91

ruby-rails-sample

Ruby
52
star
92

facebook-template-ruby

CSS
52
star
93

heroku-jupyterlab

An example of running JupyterLab on Heroku, with Amazon S3.
Python
52
star
94

heroku-maven-plugin

This plugin is used to deploy Java applications directly to Heroku without pushing to a Git repository.
Java
51
star
95

stillir

Cache environment variables as Erlang app variables
Erlang
51
star
96

rails_serve_static_assets

Ruby
49
star
97

heroku-gradle-plugin

A Gradle plugin for deploying JAR and WAR files to Heroku.
Java
49
star
98

x

A set of packages for reuse within Heroku Go applications
Go
49
star
99

template-java-spring-hibernate

Java
48
star
100

scala-getting-started

Getting Started with Scala / Play on Heroku
HTML
48
star