Last updated October 20, 2022
Webapp Runner allows you to launch an application in a Tomcat container on any computer that has a JRE installed. No previous steps to install Tomcat are required when using Webapp Runner. It’s a regular JAR file that can be executed and configured using the java command.
This article will walk you through building an application that launches with Webapp Runner and deploying that application to Heroku.
Follow each step to build an app from scratch, or skip to the end get the source for this article. You can also use almost any existing Maven webapp project.
- Create an application if you don’t already have one
- Configure Maven to download Webapp Runner
- Run your application
- Deploy your application to Heroku
- Use distributed HTTP sessions with Memcache
- Clone the source
- Basic Java knowledge, including an installed version of the JVM and Maven.
- Basic Git knowledge, including an installed version of Git.
How does Webapp Runner work?
When using Webapp Runner you’ll launch your application locally and on Heroku with a command like this:
$ java -jar webapp-runner.jar application.war deploying app from: /Users/johnsimone/dev/gitrepos/devcenter-webapp-runner/target/webappRunnerSample.war Feb 14, 2012 5:21:44 PM org.apache.coyote.AbstractProtocol init INFO: Initializing ProtocolHandler [“http-bio-8080”] Feb 14, 2012 5:21:44 PM org.apache.catalina.core.StandardService startInternal INFO: Starting service Tomcat Feb 14, 2012 5:21:44 PM org.apache.catalina.core.StandardEngine startInternal INFO: Starting Servlet Engine: Apache Tomcat/8.0.30 Feb 14, 2012 5:21:44 PM org.apache.catalina.startup.ContextConfig webConfig INFO: No global web.xml found Feb 14, 2012 5:21:44 PM org.apache.coyote.AbstractProtocol start INFO: Starting ProtocolHandler [“http-bio-8080”]
Webapp Runner will then launch a Tomcat instance with the given war deployed to it. This takes advantage of Tomcat’s embedded APIs and is similar to an option that Jetty offers: Jetty Runner. Webapp Runner is open source so you can view or contribute to the source code.
Create an application if you don’t already have one
$ mvn archetype:generate -DarchetypeArtifactId=maven-archetype-webapp … [INFO] Generating project in Interactive mode Define value for property ‘groupId’: : com.example Define value for property ‘artifactId’: : helloworld
(you can pick any groupId or artifactId). You now have a complete Java web app in the helloworld directory.
Configure Maven to download Webapp Runner
Although not necessary for using Webapp Runner it’s a good idea to have your build tool download Webapp Runner for you since your application will need it to run. You could, of course, just download Webapp Runner and use it to launch your application without doing this. However having all of your dependencies defined in your build descriptor is important for application portability and repeatability of deployment. In this case we’re using Maven so we’ll use the dependency plugin to download the jar. Add the following plugin configuration to your pom.xml:
<build> … <plugins> … <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-dependency-plugin</artifactId> <executions> <execution> <phase>package</phase> <goals><goal>copy</goal></goals> <configuration> <artifactItems> <artifactItem> <groupId>com.heroku</groupId> <artifactId>webapp-runner</artifactId> <version>188.8.131.52</version> <destFileName>webapp-runner.jar</destFileName> </artifactItem> </artifactItems> </configuration> </execution> </executions> </plugin> </plugins> </build>
The version of Webapp Runner is pinned to the version of the underlying Tomcat server. Thus, version 184.108.40.206 of Webapp Runner uses version 9.0.68 of Tomcat.
Run your application
To build your application simply run:
$ mvn package
And then run your app using the java command:
$ java -jar target/dependency/webapp-runner.jar target/*.war
That’s it. Your application should start up on port 8080.
Note: if you need your WAR file to be expanded before launching you can add the -expand-war option before target/*.war
Deploy your application to Heroku
Create a Procfile
You declare how you want your application executed in Procfile in the project root. Create this file with a single line:
web: java $JAVA_OPTS -jar target/dependency/webapp-runner.jar -port $PORT target/*.war
Deploy to Heroku
Commit your changes to Git:
$ git init $ git add . $ git commit -m “Ready to deploy”
Create the app:
$ heroku create Creating high-lightning-129… done, stack is heroku-18 http://high-lightning-129.herokuapp.com/ | firstname.lastname@example.org:high-lightning-129.git Git remote heroku added
Deploy your code:
$ git push heroku main Counting objects: 227, done. Delta compression using up to 4 threads. Compressing objects: 100% (117/117), done. Writing objects: 100% (227/227), 101.06 KiB, done. Total 227 (delta 99), reused 220 (delta 98) -> Heroku receiving push -> Java app detected -> Installing Maven 3.0.3….. done -> executing .maven/bin/mvn -B -Duser.home=/tmp/build_1jems2so86ck4 -DskipTests=true clean install [INFO] Scanning for projects… [INFO] [INFO] – [INFO] Building webappRunnerSample Maven Webapp 1.0-SNAPSHOT [INFO] – … [INFO] – [INFO] BUILD SUCCESS [INFO] – [INFO] Total time: 36.612s [INFO] Finished at: Tue Aug 30 04:03:02 UTC 2011 [INFO] Final Memory: 19M/287M [INFO] – -> Discovering process types Procfile declares types -> web -> Compiled slug size is 4.5MB -> Launching… done, v5 http://pure-window-800.herokuapp.com deployed to Heroku
Congratulations! Your web app should now be up and running on Heroku. Open it in your browser with:
$ heroku open
Deploying with the Heroku Maven Plugin
In lieu of Git deployment, you may use the Heroku Maven Plugin to deploy applications with webapp-runner. The setup for the Maven plugin is similar to what is described in this article, but there are a few key differences. In your pom.xml you will need to replace the maven-dependency-plugin with the heroku-maven-plugin and provide the proper configuration. Then, instead of deploying with a git push you will deploy with a mvn heroku:deploy-war command.
Use distributed HTTP sessions with Memcache
Explicitly storing session state in a database or other backend data store is a more scalable alternative to using distributed HTTP sessions.
Webapp runner supports the memcached-session-manager for Tomcat. In order to enable memcache backed sessions you need to make the configuration for your memcache instance available through environment variables and then enable the sesssion manager.
Make memcache configuration information available
The Heroku Memcachier Add On will set the required environment variables for you. Once you have an existing app get the add on by running:
$ heroku addons:create memcachier:dev
Note: you may have to verify your account before you can add this add on.
When running locally you can either set up a local install of memcache or connect to the remote memcache service provisioned for you by the Heroku add on.
When used with webapp runner the memcache backed session manager looks for 3 environment variables: MEMCACHIER_SERVERS, MEMCACHIER_USERNAME, MEMCACHIER_PASSWORD. You can set these to point to a local memcache install or connect to the remote memcache service provisioned for you by the Heroku add on by running heroku config and copying the values into local environment variables.
To enable memcache backed sessions with webapp runner you include the following flag: -session-store memcache
So if launching locally your command would now look like:
$ java -jar target/dependency/webapp-runner.jar -session-store memcache target/*.war
Or your Procfile would look like:
web: java $JAVA_OPTS -jar target/dependency/webapp-runner.jar -port $PORT -session-store memcache target/*.war
Clone the source
If you want to skip the creation steps you can clone the finished sample (without memcache backed session):
$ git clone https://github.com/heroku/devcenter-webapp-runner