JBoss.orgCommunity Documentation

Chapter 3. JBoss AS Crash Course

3.1. Introduction

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.

3.2. Configuring

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.

./images/jboss-server.png

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 standalone/configuration/ and domain/configuration/ folders.

Both standalone and domain modes have a common folder structure, including the following directories: configuration/, deployments/, and lib/. In general, it isn't a good idea to remove anything from these directories that you didn't put there yourself.

./images/jboss-standalone-mode.png

Some additional directories are created automatically at runtime, as needed: tmp/, data/, and log/. Though not typically necessary, you may safely delete these when the server is not running to clear its persistent state.

3.3. Running

The $JBOSS_HOME/bin/ directory contains the main JBoss entry point, standalone.sh (or standalone.bat), along with its config file, standalone.conf. Running the JBoss server is simple:

$ $JBOSS_HOME/bin/standalone.sh 

Use the --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 bin/standalone.conf. For example, your application may require more memory (RAM) than the default allocated. Edit standalone.conf to increase the value of -Xmx to something reasonable.

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.

3.4. Deploying

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.

./images/jboss-deploy.png

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.

3.5. Logging

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 standalone/configuration/logging.properties, 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 log/server.log.

Any messages written to *out* or *err* will also be displayed on the console and written to log/server.log.

Immutant 0.1.0