{"id":28551931,"url":"https://github.com/heroku/webapp-runner","last_synced_at":"2026-04-02T23:34:48.541Z","repository":{"id":2224392,"uuid":"3175490","full_name":"heroku/webapp-runner","owner":"heroku","description":"Lightweight Application Launcher. Launch your webapp in the most popular open source web container available with a single command.","archived":false,"fork":false,"pushed_at":"2025-07-01T08:01:46.000Z","size":983,"stargazers_count":325,"open_issues_count":10,"forks_count":111,"subscribers_count":79,"default_branch":"main","last_synced_at":"2025-07-01T09:20:23.775Z","etag":null,"topics":["heroku","heroku-languages","java","tomcat"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/heroku.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2012-01-14T00:21:47.000Z","updated_at":"2025-07-01T08:01:49.000Z","dependencies_parsed_at":"2023-11-06T13:30:22.339Z","dependency_job_id":"0dbf524a-0c0b-40f3-a433-3cf09688e0de","html_url":"https://github.com/heroku/webapp-runner","commit_stats":{"total_commits":484,"total_committers":32,"mean_commits":15.125,"dds":0.4276859504132231,"last_synced_commit":"8a2f0ded4ead5ec5361b8b562f3462749260c50c"},"previous_names":["jsimone/webapp-runner"],"tags_count":162,"template":false,"template_full_name":null,"purl":"pkg:github/heroku/webapp-runner","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heroku%2Fwebapp-runner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heroku%2Fwebapp-runner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heroku%2Fwebapp-runner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heroku%2Fwebapp-runner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/heroku","download_url":"https://codeload.github.com/heroku/webapp-runner/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heroku%2Fwebapp-runner/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263395305,"owners_count":23459988,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["heroku","heroku-languages","java","tomcat"],"created_at":"2025-06-10T04:07:35.380Z","updated_at":"2026-04-02T23:34:48.501Z","avatar_url":"https://github.com/heroku.png","language":"Java","readme":"# Webapp Runner [![CI](https://github.com/heroku/webapp-runner/actions/workflows/ci.yml/badge.svg?branch=tomcat9)](https://github.com/heroku/webapp-runner/actions/workflows/ci.yml) [![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.heroku/webapp-runner/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.heroku/webapp-runner)\n\nWebapp Runner is designed to allow you to launch an exploded or compressed war that is on your filesystem into a \ntomcat container with a simple `java -jar` command. It currently supports Tomcat `9.0.x` and `10.1.x`, older versions of `webapp-runner`\nfor other Tomcat versions are no longer maintained.\n\n## Table of Contents\n\n- [Usage](#usage)\n    * [Maven](#maven)\n        + [Excluding Memcached and Redis libraries](#excluding-memcached-and-redis-libraries)\n- [Store your sessions in Redis](#store-your-sessions-in-redis)\n- [Store your sessions in memcache](#store-your-sessions-in-memcache)\n- [Using behind a reverse proxy server](#using-behind-a-reverse-proxy-server)\n- [Options](#options)\n- [Development](#development)\n\n## Usage\n\nWebapp Runner is a standalone CLI tool that runs a WAR file. The simplest usage looks like this:\n\n```\n$ java -jar webapp-runner.jar path/to/project.war\n```\n\n### Maven\n\nYou can use the Maven dependency plugin to download Webapp Runner as part of your build. This will eliminate the need \nfor any external dependencies other than those specified in your build to run your application.\n\n```xml\n\u003cplugins\u003e\n  \u003cplugin\u003e\n      \u003cgroupId\u003eorg.apache.maven.plugins\u003c/groupId\u003e\n      \u003cartifactId\u003emaven-dependency-plugin\u003c/artifactId\u003e\n      \u003cversion\u003e3.3.0\u003c/version\u003e\n      \u003cexecutions\u003e\n          \u003cexecution\u003e\n              \u003cphase\u003epackage\u003c/phase\u003e\n              \u003cgoals\u003e\n                  \u003cgoal\u003ecopy\u003c/goal\u003e\n              \u003c/goals\u003e\n              \u003cconfiguration\u003e\n                  \u003cartifactItems\u003e\n                      \u003cartifactItem\u003e\n                          \u003cgroupId\u003ecom.heroku\u003c/groupId\u003e\n                          \u003cartifactId\u003ewebapp-runner\u003c/artifactId\u003e\n                          \u003cversion\u003e${webapp-runner.version}\u003c/version\u003e\n                          \u003cdestFileName\u003ewebapp-runner.jar\u003c/destFileName\u003e\n                      \u003c/artifactItem\u003e\n                  \u003c/artifactItems\u003e\n              \u003c/configuration\u003e\n          \u003c/execution\u003e\n      \u003c/executions\u003e\n  \u003c/plugin\u003e\n\u003c/plugins\u003e\n```\n\nNow when you run `maven package`, Webapp Runner will be downloaded for you. You can then launch your application with:\n\n```\n$ java -jar target/dependency/webapp-runner.jar target/\u003cappname\u003e.war\n```\n\n#### Excluding Memcached and Redis libraries\n\nWebapp Runner bundles Memcached and Redis client libraries into it's package. These libraries can cause \nconflicts with similar libraries in your application. This frequently manifests itself as a \n`java.lang.NoSuchMethodError`.\n\nIf you do not require these client libraries (because you are storing session data in some other way), you can exclude \nthem by using `webapp-runner-main` instead of `webapp-runner`:\n\n```xml\n\u003cartifactItem\u003e\n    \u003cgroupId\u003ecom.heroku\u003c/groupId\u003e\n    \u003cartifactId\u003ewebapp-runner-main\u003c/artifactId\u003e\n    \u003cversion\u003e${webapp-runner.version}\u003c/version\u003e\n    \u003cdestFileName\u003ewebapp-runner.jar\u003c/destFileName\u003e\n\u003c/artifactItem\u003e\n```\n\n## Store your sessions in Redis\n\nWebapp Runner includes a [session manager that stores sessions in redis](https://github.com/redisson/redisson).\n\nTo use it, add `--session-store redis` to your startup command:\n\n```\n$ java -jar webapp-runner.jar --session-store redis target/\u003cappname\u003e.war\n```\n\nThe session store is configured via the following environment variables: \n\n- `REDIS_URL` \n\n## Store your sessions in memcache\n\nWebapp Runner includes a [session manager that stores sessions in memcache](https://github.com/magro/memcached-session-manager).\n\nTo use it, add `--session-store memcache` to your startup command:\n\n```\n$ java -jar webapp-runner.jar --session-store memcache target/\u003cappname\u003e.war\n```\n\nThe session store is configured via the following environment variables:\n\n- `MEMCACHE_SERVERS`\n- `MEMCACHE_USERNAME`\n- `MEMCACHE_PASSWORD`\n\n## Using behind a reverse proxy server\n\nIf you are using webapp-runner behind a proxy server, you can set the proxy base url within tomcat:\n\n```\n$ java -jar webapp-runner.jar --proxy-base-url https://example.com target/\u003cappname\u003e.war\n```\n\nIf 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.\n\n## Options\n\n```\nUsage: \u003cmain class\u003e [options]\n  Options:\n    --access-log\n      Enables AccessLogValue to STDOUT\n      Default: false\n    --access-log-pattern\n      If --access-log is enabled, sets the logging pattern\n      Default: common\n    --basic-auth-pw\n      Password to be used with basic auth. Defaults to BASIC_AUTH_PW env\n      variable.\n    --basic-auth-user\n      Username to be used with basic auth. Defaults to BASIC_AUTH_USER env\n      variable.\n    --bind-on-init\n      Controls when the socket used by the connector is bound. By default it\n      is bound when the connector is initiated and unbound when the connector\n      is destroyed., default value: true\n      Default: true\n    --compressable-mime-types\n      Comma delimited list of mime types that will be compressed when using\n      GZIP compression.\n      Default: text/html,text/xml,text/plain,text/css,application/json,application/xml,text/javascript,application/javascript\n    --context-xml\n      The path to the context xml to use.\n    --enable-basic-auth\n      Secure the app with basic auth. Use with --basic-auth-user and\n      --basic-auth-pw or --tomcat-users-location\n      Default: false\n    --enable-client-auth\n      Specify -Djavax.net.ssl.keyStore and -Djavax.net.ssl.keyStorePassword in\n      JAVA_OPTS\n      Default: false\n    --enable-compression\n      Enable GZIP compression on responses\n      Default: false\n    --enable-naming\n      Enables JNDI naming\n      Default: false\n    --enable-ssl\n      Specify -Djavax.net.ssl.keyStore, -Djavax.net.ssl.keystoreStorePassword,\n      -Djavax.net.ssl.trustStore and -Djavax.net.ssl.trustStorePassword in\n      JAVA_OPTS. Note: should not be used if a reverse proxy is terminating\n      SSL for you (such as on Heroku)\n      Default: false\n    --expand-war-file\n      Expand the war file and set it as source\n      Default: true\n    --expanded-dir-name\n      The name of the directory the WAR file will be expanded into.\n      Default: expanded\n    --help\n\n    --max-threads\n      Set the maximum number of worker threads\n      Default: 0\n    --memcached-transcoder-factory-class\n      The class name of the factory that creates the transcoder to use for\n      serializing/deserializing sessions to/from memcached.\n    --path\n      The context path\n      Default: \u003cempty string\u003e\n    --port\n      The port that the server will accept http requests on.\n      Default: 8080\n    --proxy-base-url\n      Set proxy URL if tomcat is running behind reverse proxy\n      Default: \u003cempty string\u003e\n    --scanBootstrapClassPath\n      Set jar scanner scan bootstrap classpath.\n      Default: false\n    --session-store\n      Session store to use (valid options are 'memcache' or 'redis')\n    --session-store-ignore-pattern\n      Request pattern to not track sessions for. Valid only with memcache\n      session store. (default is '.*\\.(png|gif|jpg|css|js)$'. Has no effect\n      for 'redis')\n      Default: .*\\.(png|gif|jpg|css|js)$\n    --session-store-locking-mode\n      Session locking mode for use with memcache session store. (default is\n      all. Has no effect for 'redis')\n      Default: all\n    --session-store-operation-timeout\n      Operation timeout for the memcache session store. (default is 5000ms)\n      Default: 5000\n    --session-store-pool-size\n      Pool size of the session store connections (default is 10. Has no effect\n      for 'memcache')\n      Default: 10\n    --session-store-ssl-endpoint-identification\n      Enables or disables SSL endpoint identification for the redis session\n      store. (default is true. Has no effect for 'memcache')\n      Default: true\n    --session-timeout\n      The number of minutes of inactivity before a user's session is timed\n      out.\n    --shutdown-override\n      Overrides the default behavior and casues Tomcat to ignore lifecycle\n      failure events rather than shutting down when they occur.\n      Default: false\n    --temp-directory\n      Define the temp directory, default value: ./target/tomcat.PORT\n    --tomcat-users-location\n      Location of the tomcat-users.xml file. (relative to the location of the\n      webapp-runner jar file)\n    --uri-encoding\n      Set the URI encoding to be used for the Connector.\n    --use-body-encoding-for-uri\n      Set if the entity body encoding should be used for the URI.\n      Default: false\n    --secure-error-report-valve\n      Set true to set ErrorReportValve properties showReport and showServerInfo to false. This protects from Apache stacktrace logging of malicious http requests. \n      Default: false\n    -A\n      Allows setting HTTP connector attributes. For example: -Acompression=on\n      Syntax: -Akey=value\n      Default: {}\n```\n\nSee the Tomcat documentation for a [complete list of HTTP connector attributes](https://tomcat.apache.org/tomcat-9.0-doc/config/http.html).\n\n## Development\n\nTo run the entire suite of integration tests, use the following command:\n\n```\n$ ./mvnw clean install -Pintegration-test\n```\n\nTo run an individual integration test, use a command like this:\n\n```\n$ ./mvnw clean install -Pintegration-test -Dinvoker.test=memcache-test\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheroku%2Fwebapp-runner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fheroku%2Fwebapp-runner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheroku%2Fwebapp-runner/lists"}