Installation Guide

Installation of Immutant 1.x was atypical of most Clojure libraries, because that distribution included a fork of the JBoss AS7 application server. In Immutant 2.x, the application server is gone, so there is no explicit installation step.

project.clj

To use Immutant, you need two things in your project.clj:

• Immutant lib[s] in your :dependencies
• a :main function or namespace

:dependencies

Here’s an example making all the Immutant libraries available in a project’s classpath:

(defproject some-project "1.2.3"
  ...
  :dependencies [[org.immutant/web "2.1.9"]
                 [org.immutant/caching "2.1.9"]
                 [org.immutant/messaging "2.1.9"]
                 [org.immutant/scheduling "2.1.9"]
                 [org.immutant/transactions "2.1.9"]])

You would of course only include the libs you need, but if you really did use all of them, or you just want to experiment, we provide an aggregate that brings them all in transitively:

(defproject some-project "1.2.3"
  ...
  :dependencies [[org.immutant/immutant "2.1.9"]]

NOTE: There is another library providing utility functions relevant only within WildFly that is not brought in by the aggregate. If your app relies on the immutant.wildfly namespace and you wish to compile it outside the container, you’ll need to explicitly depend on org.immutant/wildfly in your project.clj:

(defproject some-project "1.2.3"
  ...
  :dependencies [[org.immutant/immutant "2.1.9"]
                 [org.immutant/wildfly "2.1.9"]]

See the WildFly guide for details.

:main

With the dependencies in place, you simply invoke the Immutant services from your app’s main entry point, identified by the :main key in your project.clj.

If you created your project with the app template, like so:

lein new app my-app

Then the value of the :main entry in project.clj will be my-app.core and the -main function in src/my_app/core.clj is where you should invoke the Immutant services. For example:

(ns my-app.core
  (:require [immutant.web :as web])
  (:gen-class))

(defn app [request]
  {:status 200
   :body "Hello world!"})

(defn -main []
  (web/run app))

You can also specify a fully-qualified symbol for :main that points to function to use instead of -main:

:main my-app.core/start

But what if your project doesn’t have a :main function? Perhaps you created your app with a popular Ring-based template like Compojure:

lein new compojure my-app

Instead of a :main, you’ll have a :ring map with a :handler called my-app.handler/app. So you’ll need to manually add a :main entry referencing a function in your project. You can easily add one to src/my_app/handler.clj:

(ns my-app.handler
  ...
  (:require [immutant.web :as web])
  ... )

(def app ... )

(defn start []
  (web/run app))

With :main set to my-app.handler/start in project.clj, you can then start your app like so:

lein run

If you are deploying your application to WildFly, see the WildFly guide for information on how :main is handled there.

Incremental Builds

If you need cutting-edge features/fixes that aren’t in the latest release, you can use an incremental build.

Our CI server publishes an incremental release for each successful build. In order to use an incremental build, you’ll need to add a repository to your project.clj:

(defproject some-project "1.2.3"
  ...
  :dependencies [[org.immutant/immutant "2.x.incremental.BUILD_NUMBER"]]
  :repositories [["Immutant 2.x incremental builds"
                  "http://downloads.immutant.org/incremental/"]])

You should replace BUILD_NUMBER with the actual build number for the version you want to use. You can obtain this from our builds page.

Additional Resources

The API docs for the latest Immutant release are always available here:

• /documentation/current/apidoc/

as well as the API docs for the latest CI build.

If you are interested in using Immutant inside a WildFly container, see our WildFly guide.