Parallel Universe

Packaging: small, portable and convenient

Packages any JVM application, no matter how complex, as a single, plain executable JAR. A capsule may directly contain all of the application’s dependencies or simply declare some or all of them, to be downloaded when launched. Built with standard build tools, it is the fat JAR that always works.

Installation: minimal impact on host, supports updates

A capsule installs itself the first time it is run by creating some files in a temporary directory. It may also optionally look for updates, either to the application or its dependencies, and download them when it launches. Those dependencies may be shared by other capsules.

Launch: deterministic yet flexible, possibly secure and optionally restricted

No startup scripts required. The capsule looks for the requested JVM version, sets up the classpath and necessary agents and sets the JVM flags. Capsules can also create their own safe, unprivileged containers.

What is Capsule?

Capsule is an open-source packaging and deployment tool for JVM applications. A capsule is a single executable JAR that contains everything your application needs to run either in the form of embedded files or as declarative metadata. It can contain your JAR artifacts, your dependencies and resources, native libraries, the required JRE version, the JVM flags required to run the application, Java or native agents and more. In short, a capsule is a self-contained JAR that knows everything there is to know about how to run your application the way it's meant to run.

One way of thinking about a capsule is as a fat JAR on steroids (that also allows native libraries and never interferes with your dependencies) and a declarative startup script rolled into one; another, is to see it is as the deploy-time counterpart to your build tool. Just as a build tool manages your build, Capsule manages the launching of your application.

But while plain capsules are cool and let you ship any JVM application -- no matter how complex -- as a single executable JAR, caplets make capsules even more powerful.

What are Caplets?

Caplets are classes that hook into the capsule and modify its behavior. A capsule contains metadata about your application and the means to execute it as a plain JVM program. Caplets can use the metadata in the capsule to launch the application in some more sophisticated ways, or even change the way it is packaged.

A caplet can be embedded in the capsule, or be packaged separately and used to wrap an existing capsule. While every caplet can be embedded or used as a wrapper, usually just one of the options makes sense.

See here for a list of available caplets

Cool Stuff You Can Do with Capsules

Run a capsule as a minimal, secure (unprivileged) Linux Container that automatically pumps JMX monitoring and standard Java logging outside the container.
Have your JAR automatically choose an appropriate JVM version, set JVM flags, and add an embedded JAR to the boot class path.
Embed any required native libraries directly in the JAR, and Capsule automatically makes sure your application finds them.
Distribute your application as an "executable WAR": it can be deployed to a servlet container or, if executed directly, by use of the Maven caplet it will automatically download Jetty and deploy itself into the embedded container.
Distribute a Clojure application without embedding Clojure itself in the capsule, and have Clojure downloaded the first time the capsule is launched. The Clojure runtime will be cached and shared among all Clojure capsules so it will only be downloaded once.
Turn any capsule into an OS-specific native application or daemon.

How Capsule Works

When you include the Capsule class in your JAR file and set it to serve as the JAR's main class, Capsule reads various configuration values (like JVM arguments, environment variables, Maven dependencies and more) and caplets from the JAR's manifest. It then optionally extracts the JAR's contents into a cache directory, performs custom caplet operations, picks a JVM installation based on the version requirements in the manifest, and finally, it spawns another JVM process to run your application as configured.

Capsule