Tutorial: Installation

This tutorial provides an in-depth look at the process for installing Immutant. It covers setting up a development environment and installing Immutant itself. This tutorial assumes you are on a *nix system. It also assumes you have Leiningen installed. If not, follow these instructions then come back here.

Installing the lein plugin

We provide a lein plugin for creating your Immutant applications and managing their life-cycles. The current version of the plugin is 1.2.3.

The plugin only supports Leiningen 2.0.0 and higher.

Installing under Leiningen

Installing the plugin for Leiningen is just a matter of adding it to the :plugin list in the :user profile of ~/.lein/profiles.clj:

{:user {:plugins [[lein-immutant "1.2.3"]]}}

Plugin tasks

The plugin provides several subtasks, but this tutorial will only focus on install and run. To list all of them, simply run lein immutant:

$ lein immutant

Installing Immutant

Now we need to install an Immutant distribution. You have the option of either installing a versioned release or an incremental build. Our latest versioned release is 1.1.4 (released Friday, August 1, 2014), but if you want to stay on the cutting edge, you may want to install the latest incremental build. We generate one after every push to our repo if our comprehensive test suite passes.

The plugin provides an install subtask that can install a versioned release, the latest incremental release, or any prior incremental release.

To install the latest versioned release, call immutant install with no arguments:

$ lein immutant install
Downloading http://repository-projectodd.forge.cloudbees.com/release/org/immutant/immutant-dist/1.1.4/immutant-dist-1.1.4-slim.zip
done!
Extracting /a/nice/long/tmp/path/immutant-dist-1.1.4-slim.zip
Extracted /Users/tobias/.immutant/releases/slim/immutant-1.1.4-slim
Linking /Users/tobias/.immutant/current to /Users/tobias/.immutant/releases/immutant-1.1.4-slim

Part of the install process links the most recently installed version to ~/.immutant/current so the plugin can find the Immutant install without requiring you to set $IMMUTANT_HOME. If $IMMUTANT_HOME is set, it will override the current link.

Passing the special word LATEST will install the latest incremental build:

$ lein immutant install LATEST

If you want to install a specific version (either an incremental build or a release), specify the build number (available from our builds page) for an incremental build:

$ lein immutant install 705

or a version for a release:

$ lein immutant install 1.1.4

You can list your installations, and see the current one, with the list subtask:

$ lein immutant list -i

The install command also verifies the sha1 sum of the downloaded artifact, and will abort the installation if the sum is incorrect.

You can override the plugin base directory (~/.immutant) by setting $LEIN_IMMUTANT_BASE_DIR or by adding :lein-immutant {:base-dir "/path"} to your user profile in .lein/profiles.clj or to your project.clj. Setting the base directory in project.clj will override the setting in .lein/profiles.clj. Using the environment variable will override both.

Running Immutant

To verify that Immutant is properly installed, let's fire it up. To do so, use the lein immutant run command. This is a convenient way to start the Immutant's JBoss server, and will run in the foreground displaying the console log. You'll see lots of log messages that you can ignore - the one to look for should be the last message, and will tell you the Immutant was properly started:

$ lein immutant run
Starting Immutant via /Users/tobias/.immutant/current/jboss/bin/standalone.sh
...
(a plethora of log messages deleted)
...
09:18:03,709 INFO  [org.jboss.as] (Controller Boot Thread) JBAS015874: JBoss AS 7.1.x.incremental.107 "Arges" started in 1610ms - Started 166 of 252 services (85 services are passive or on-demand)

You can kill the Immutant with Ctrl-C.

Alternate Install via Zip Download

You can manually download any of the same builds that you can install via the plugin. You can download incremental builds from the builds page and official releases from the releases page.

Once you have the zip downloaded, expand it somewhere handy. If you want to use the Leiningen plugin with this build, you'll need to set $IMMUTANT_HOME:

$ mkdir immutant-releases
$ cd immutant-releases
$ unzip path/to/immutant-dist-slim.zip
$ export IMMUTANT_HOME=~/immutant-releases/immutant-1.1.4-slim/

Wrapping up

If you've done all of the above, you're now ready to deploy an application. We cover that in our deployment tutorial.

If you have any feedback or questions, get in touch!