WAR Deployment

In this guide we’ll show a very simple application, yet another "hello world" service.

We’ll show how to package up the application’s sources, resources, and library dependencies into a WAR file.

Finally, we’ll demonstrate how to deploy the WAR file into a Jetty service running inside a Docker container.

You’ll need to have Docker installed as part of this guide.

We’ve mentioned deployments and WAR files, so let’s detour into some more specifics about what a WAR file actually is.

A WAR file is an archive file, like a .zip or .jar file, with a particular structure.

This structure provides the servlet container with the information it needs to set up a classloader specifically for the deployed WAR file, and direct incoming HTTP requests into it.

As with the other guides, we’ll define the dependencies of our project using a deps.edn file.

The main dependency is on io.pedestal/pedestal.servlet; all other necessary Pedestal dependencies are provided as transitive dependencies from this. pedestal.servlet is not linked to any particular implementation of the Servlet API.

In a servlet container deployment, the WAR file normally does not have dependencies on the Servlet API; the servlet container, which has control over the classpath of the deployed WAR, adds the Servlet API in automatically. pedestal.servlet does not have a dependency on the Servlet API --- well, actually, it does under development and when compiling some Java classes, but it doesn’t export those dependencies to projects like this one.

However, using WebSockets is different ^[1] and if the WAR file makes use of WebSockets it must include the WebSocket API (mostly interfaces) and implementation files (classes implementing those interfaces). These should be matched to the servlet container, so we’re using the Jetty implementations here.

Even though this application doesn’t use WebSockets, the Pedestal libraries do have WebSocket support built-in, so these dependencies must be included, even if they won’t be actively used.

Our application is very simple, it responds to the URL GET /hello and responds with a snippet of text.

This is all the code for our application (!) --- we’ve skimped on writing tests.

The connection-map function is used to create a connection map as if we were going to create a reference:connector.adoc …​ but we stop short. In fact, all we really care about at the end are the :interceptors and :initial-context keys of this connection map.

The magic happens in the create-bridge function; this will be invoked from the servlet to create the ConnectorBridge object. The api:create-bridge[ns=io.pedestal.connector.servlet] function does the heavy lifting.

This bridge object has a service method that is passed the HttpServletRequest and HttpServletResponse and does all the Pedestal-related processing.

Inside all this XML are three basic constructors:

So, the request comes into the Jetty servlet container and it decides which WAR deployment it belongs to, then which servlet inside the WAR deployment is responsible, then asks the servlet to do the work, which passes through the ConnectorBridge and into Pedestal to do the actual work.

To create a WAR file, we need to package up the sources, the deployment descriptor, and any libraries, such as pedestal.servlet (and all the its transitive dependencies). We can do this in a quick-and-dirty style using a small amount of Clojure code.

When we discussed dependencies, there was a :build alias: this build alias sets up build as a classpath root, and brings in dependencies on io.github.clojure/tools.build (for reading the deps.edn file) and babashka/fs (for copying files and building archives).

A basis is a fully expanded definition of the contents of the deps.edn file, including all the source roots, direct dependencies, and transitive dependencies. We use all that to copy files to a working directory, and then we package it all together as a WAR file.

The command clojure -T:build war will run this code:

This is just a minimal example; a more complete version might:

Now that we have a WAR file, we can show how to deploy it.

We’ll make use of Docker to simplify deployment …​ really, to not leave a mess on your computer after we’re done.

A Dockerfile describes how to build a Docker image — a snapshot of a virtual computer running some kind of Linux with everything installed and configured and ready to go. Most of the work was done for us in the image we extend from, and standard jetty 12 image.

It’s just a matter of enabling WAR deployments and copying the app.war file into the image.

The WAR files go in the /var/lib/jetty/webapps folder inside the Docker image, and the special name ROOT.war is recognized by Jetty as a WAR file that deploys without any kind of prefix on the path.

You can build this manually with docker build …​, and run it with docker run …​ …​ but our final step is to show a simple script file that puts all the pieces together

To simplify things, we’ll provide a script that puts everything together and ensures that Jetty is running:

This script builds the WAR file, then builds the Docker image and tags it as war-demo. Finally, it starts Docker executing the image in a new container, and it binds port 8080 on your computer to port 8080 inside the Docker container. That’s the default port that Jetty uses.

If we run that script:

Again, there will be a lot of downloads the first time you run this script …​ but in the end, Jetty starts up and immediately deploys the ROOT.war file.

Jetty will continue to run until you enter Ctrl-C, so in another window, you can use curl to send a request to the application:

The -v option shows the headers and data sent and received; you can not only see the content provided by the hello handler function, but you can also see all the headers provided by the default interceptors.

Deploying a Pedestal application as a WAR file is a completely viable approach, especially useful when the Pedestal application must work along-side pure-Java servlets and servlet filters.

In fact, the Clojure code is the smallest part of this guide - much work was needed to package up the code into a WAR file, and a bit more (specific to this guide) to deploy that WAR file into a Docker container.