Chapter 3. JBoss AS Crash Course
The JBoss Application Server (AS7) is the foundation upon which Immutant is built. You can go a long way with Immutant without knowing anything about the administration of JBoss AS, but for advanced applications, it's worth knowing something about how AS is configured and extended. Feel free to skip this section if you're just getting started with Immutant, and use it as a reference later.
For more detailed documentation, please read the official AS7 docs.
In AS7, all server configuration is kept in two folders, one for each runtime mode: standalone and domain. Administrative tasks are simplified from previous releases because all configuration is in one folder and, in standalone mode, in a single file.
Immutant uses standalone mode by default but can be run in domain mode as well.
JBoss AS 7 uses a modular architecture - libraries common to all server
configurations are kept under the
modules/ directory. Configuration files
are stored inside
Both standalone and domain modes have a common folder structure, including
the following directories:
In general, it isn't a good idea to remove anything from these directories
that you didn't put there yourself.
Some additional directories are created automatically at runtime, as needed:
log/. Though not typically necessary, you may safely
delete these when the server is not running to clear its persistent state.
$JBOSS_HOME/bin/ directory contains the main JBoss entry point,
standalone.bat), along with its config file,
standalone.conf. Running the JBoss server is simple:
--server-config option to specify a different configuration. For
example, to put JBoss in "clustered" mode:
$ $JBOSS_HOME/bin/standalone.sh --server-config=standalone-ha.xml
You may set Java system properties using the
-D option. Pass
-h for a
list of all the available options.
Permanent runtime configuration of JBoss should go in
For example, your application may require more memory (RAM) than the default
standalone.conf to increase the value of
-Xmx to something
In production you may prefer to control JBoss via a Unix "init script", examples
of which may be found in
bin/. Feel free to tweak one for your particular OS.
Each runtime mode has a
deployments/ subdirectory, the contents of which
determine the applications and services JBoss runs. These apps and services
are represented as archives, "exploded" folders, or text files called
"deployment descriptors". The JBoss deployment scanner operates in two different
modes: auto-deploy and manual deploy.
Auto-deploy mode works like in previous releases of AS, in that a resource will be redeployed every time the its timestamp changes. The scanner creates a marker file with a ".deployed" suffix, and if the resource gets deleted the scanner will not trigger an undeployment.
In manual deploy mode the scanner will rely on addition or removal of a marker files. To more about this deployment method, see the marker files section of the administrator guide.
The lein-immutant Leiningen plugin provides commands to create and copy a
deployment descriptor for your Clojure application to
$IMMUTANT_HOME/standalone/deployments/. See Deployment for more details.
Each runtime mode has a
log/ subdirectory (created at runtime, if necessary)
that contains the log messages generated by JBoss as determined by its configuration.
JBoss provides a very sophisticated logging system that nobody completely understands.
Logging configuration rules are contained in
in which may be found example configs for categorized log message routing, complex file
rotation, syslog integration, SMTP notifications, SNMP traps, JMS, JMX and more! It is WAY
beyond the scope of this document to explain those rules, but by default you will see INFO
messages on the console (the shell where you start JBoss) and persistently written to
Any messages written to
*err* will also be displayed on the console and