Chapter 3. Deploying Clojure Applications

Applications can be deployed to Immutant as a directory on disk, or as an archive. The actual deployment process can be done manually or using the lein-immutant Leiningen plugin. See the Installation chapter for details on how to install the plugin.

To manually deploy any artifact to Immutant, you follow the standard AS7 deployment method. Deploying consists of creating two files in $JBOSS_HOME/standalone/deployments/: the artifact itself, and a marker file that tells Immutant that you have finished creating the artifact. This marker file has the same name as the artifact, but with the .dodeploy suffix appended, and has no content. Example:

$ cp thing-to-deploy $JBOSS_HOME/standalone/deployments/
$ touch thing-to-deploy.dodeploy $JBOSS_HOME/standalone/deployments/

Luckily, you should rarely need to manually deploy your artifacts - the plugin takes care of that for you.

To deploy an application from where it sits on disk (in other words, without having to create an archive), simply call the deploy subtask of the plugin. The deploy subtask optionally accepts the path to the project. If no path is specified, the current working directory is assumed:

$ lein immutant deploy
# or
$ lein immutant deploy path/to/project

This generates and deploys a deployment descriptor that refers to the location of the application on disk. See the descriptor section below for more details.

The lein-immutant plugin provides additional deploy options - see its README for details.

Immutant supports deployment of archives that have been generated by the lein-immutant plugin. An Immutant archive is simply a zip file with a specific format that ends with a .ima suffix. Currently, the only supported way to generate an Immutant archive is via the plugin. The archive subtask optionally accepts the path to the project. If no path is specified, the current working directory is assumed. In either case, the .ima is written to the current working directory. Example usage:

$ lein immutant archive
# or
$ lein immutant archive path/to/project

The archive subtask creates the archive using the following process:

1. The application's dependencies are resolved into the local maven repository
2. Those resolved dependencies are copied to lib/ at the root of the project
3. The lib/ dir is zipped up along with the src/, resources/, target/native, classes, and target/classes dirs, as well as the project.clj.

The archive process honors the :library-path, :source-path(s), :resources-path(s) :native-path, and :compile-path options of project.clj, allowing you to override the default directories.

Calling the archive subtask directly gives you an .ima that you can then manually deploy. To deploy an archive via the plugin, simply pass the --archive option to the deploy subtask. The deploy subtask optionally accepts the path to the project. If no path is specified, the current working directory is assumed:

$ lein immutant deploy --archive
# or
$ lein immutant deploy --archive path/to/project

If no .ima archive exists in the current working directory, it will be generated before being deployed.

In addition to deploying an .ima directly, you can also manually deploy a deployment descriptor that refers to the location of the archive. See the descriptor section below for more details.

The lein-immutant plugin provides additional archive and deploy options - see its README for details.

An Immutant deployment descriptor is simply a Clojure file containing a map of options. When a descriptor is deployed, Immutant loads the file, evaluating all its forms, and uses it to determine where the actual application resides by looking at its :root entry. The :root entry can either be the path to the application root on disk, or the path to an .ima archive. For details on the format of the deployment descriptor, see Configuration Options.

Regardless of how you deploy your app, it will only run if Immutant itself is running. This is easily accomplished using the plugin:

$ lein immutant run

Simply type Ctrl-c to exit, but you may as well leave it up. You can deploy and undeploy as many applications as your RAM will allow to a single Immutant instance.

Out of the box, Immutant is only accessible from localhost. To access it from other machines pass the -b parameter to bind to a real IP address or any available IP address:

$ lein immutant run -b 10.100.10.25
$ lein immutant run -b 0.0.0.0

It's also possible to run Immutant in "clustered" mode. Doing so in a network with multicast enabled causes Immutants to discover each other and, for example, easily distribute work via a message queue across a linearly-scalable data grid.

Just by doing this:

$ lein immutant run --clustered