Chapter 3. Deploying Clojure Applications
3.1. Introduction
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.
3.2. Manually Deploying Artifacts
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 $JBOSS_HOME/standalone/deployments/thing-to-deploy.dodeploy
Luckily, you should rarely need to manually deploy your artifacts - the plugin takes care of that for you.
3.3. Directory-based Deployment
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.
3.4. Archive-based Deployment
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 can optionally contain the application's
dependencies. They are included by default, but will be excluded if
the --exclude-dependencies
option is passed to the archive
subtask.
The archive
subtask creates the archive using the following process:
- If dependencies are to be included, they are resolved into the
local maven repository, and then included in the zip archive
under
lib/
. - From the project root, the
src/
,resources/
,target/native/
,classes/
,target/classes/
, andlib/
dirs are included in the zip, as well as theproject.clj
.
The archive process honors the :source-paths
, :resources-paths
,
: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
A new .ima
archive will be generated each time deploy is invoked.
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.
3.5. Deployment Descriptor
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.
3.6. Running Immutant
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 in your development environment. You can deploy and undeploy as many applications as your RAM will allow to a single Immutant instance.
The run
task is a thin wrapper around the JBoss standalone.sh script, so in addition to a few "convenience options", all of the
JBoss options are supported as well. Run the following commands to
list them:
$ lein help immutant run $ lein immutant run -h
JBoss makes much use of Java system properties for its
configuration. These are set using the -D
option, e.g.
-Dproperty\=value
. Here are some common ones:
System Property | Default | Description |
---|---|---|
http.port | 8080 | The port on which Immutant listens for web requests |
jboss.logging.level | INFO | The console's logging level threshold |
org.immutant.web.http.maxThreads | 512*#cores | Thread pool size for HTTP connection handlers |
Other system properties can be found in the JBoss configuration
file, $JBOSS_HOME/standalone/configuration/standalone.xml
(or
standalone-ha.xml
if clustered). In that file, any attribute of
the form ${property:default}
denotes a system property and its
corresponding default value if unset, like ${http.port:8080}
, so
to override that, you could run either of the following:
$ lein immutant run -Dhttp.port=7777 $ ~/.immutant/current/jboss/bin/standalone.sh -Dhttp.port=7777
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 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.
To run in clustered mode, either of the following should work:
$ lein immutant run --clustered $ ~/.immutant/current/jboss/bin/standalone.sh --server-config=standalone-ha.xml