Why use a Shared JBoss Installation Directory?

Development teams typically have a development lab consisting of shared hardware for testing deployments in a more 'production-like' way. The shared hardware usually has multiple instances of the application deployed on it (a few instances per developer), and one installation of the application server software. For example, on a Linux system it would be common for applications such as JBoss to be installed in the /usr/local directory, and the individual developer instances of the application to be deployed in each user's home directory, or perhaps some other part of the filesystem set up explicitly for deployments. So, you may need a shared installation directory for a number of reasons.

1. You want to have a directory for each instance of JBoss somewhere other than in the JBoss installation 'server' directory.
2. There is a shared (Linux or Unix) deployment box where each user refers to the JBoss installation directory which is read only for their account. (Of course, you could have each user have their own copy of JBoss, but that isn't a very good use of disk space)
3. The JBoss installation is on a network drive and read only.

Default directory setup

After installation, the JBoss home directory will have a server directory under it which will contain a directory for each 'configuration' or 'server name'. Each of these will have a 'deploy' directory underneath it. For example:

JBOSS_HOME
   \- server
      +- default
      \- minimal

For a shared installation, it might not work to have the subdirectories of 'server' for each configuration, or user. So that leaves two problems that must be solved:

1. How do we tell JBoss to use some directory other than $JBOSS_HOME/server for deployments / configurations?
2. How do we run multiple instances of JBoss on the same server?

JBoss System Properties

Fortunately, it is quite simple to start JBoss so that it will use a shared installation. The key is to understand how to use the JBoss system properties. These properties depend on each other, care must be taken to set them properly.

JBoss 4.x System Properties

Where are the ports defined?

See JBoss Ports

Examples of setting jboss.server.home

Example 1 - Linux

Suppose JBoss is installed in /usr/local/jboss and there is an application deployment in /home/jdavis/myapp. Before starting up JBoss we will need to set some environment variables. We can make a shell script to do this:

#!/bin/bash
# start-env.sh - starts a new shell with instance variables set
export JBOSS_HOME=/usr/local/jboss
JAVA_HOME=/usr/java/jdk1.5.0_04
export PATH=$JAVA_HOME/bin:$JBOSS_HOME/bin:$PATH
echo "Runtime shell..."
$SHELL

~_{Note that this script will start a new shell}~, so you can simply exit the shell at any time to go back to the environment variables you had before.

Now, we need to get a sample deployment. For this example, we can copy the 'default' configuration in the JBoss server directory.

$ ./start-env.sh
$ cp -r $JBOSS_HOME/server/default /home/jdavis/myapp

We can now start the 'myapp' server like this:

$ run.sh -Djboss.server.base.dir=/home/jdavis \
    -Djboss.server.base.url=file:///home/jdavis -c myapp

In this example we've set the server base directory to the directory above the application deployment and used the -c option to specify the sub-directory, which is the default behavior. Also note that the prefix for the URL form of the base directory is file://. The third forward slash is for the filesystem root directory.

Example 2 - Cygwin

This is the same as the previous example, except:

1. Java is installed in D:/java/jdk1.5.0_04
2. We need to translate the JAVA_HOME path after putting it in the PATH.

Also, Cygwin is installed in D:/cygwin

Here is the modified shell script:

#!/bin/bash
# start-env.sh - starts a new shell with instance variables set
export JBOSS_HOME=/usr/local/jboss
JAVA_HOME=/cygdrive/d/java/jdk1.5.0_04
export PATH=$JAVA_HOME/bin:$JBOSS_HOME/bin:$PATH
export JAVA_HOME=`cygpath --mixed $JAVA_HOME`
echo "Runtime shell..."
$SHELL

Now, we need to get a sample deployment. For this example, we can copy the 'default' configuration in the JBoss server directory.

$ ./start-env.sh
$ cp -r $JBOSS_HOME/server/default /home/jdavis/myapp

We can now start the 'myapp' server like this:

$ run.sh -Djboss.server.base.dir=D:/cygwin/home/jdavis \
     -Djboss.server.base.url=file:/D:/cygwin/home/jdavis -c myapp

In this example, we've set the server base directory to the directory above the application deployment and used the

-c

option to specify the sub-directory, which is the default behavior. Note that under Cygwin, the URL prefix is quite different. In this case, the prefix is file:/ followed by the drive letter and then the rest of the path.

Example 3 - Windows Command Shell

This is the equivalent of the previous example.

1. Java is installed in D:/java/jdk1.5.0_09
2. JBoss in installed in D:/java/jboss-4.0.5.GA
3. The local deployment is in D:/jdavis/myapp

Here is the CMD script to start JBoss on the local deployment:

set JBOSS_HOME=D:/java/jboss-4.0.5.GA
set JAVA_HOME=D:/java/jdk1.5.0_09
call %JBOSS_HOME%/bin/run.bat -Djboss.server.base.dir=D:/jdavis   \
     -Djboss.server.base.url=file:/D:/jdavis -c myapp

In this example, we've set the server base directory to the directory above the application deployment and used the

-c

option to specify the sub-directory, which is the default behavior.

Deployment

See JBoss Deployment Directory