[toc]

Introduction
============

[JBoss AS](http://www.jboss.org/jbossas/) is a Java EE-certified application server coming from the Free Software giant [Red Hat](http://www.redhat.com/). Coming both as a free (as in beer) piece of software, Red Hat provides commercial support for it as well. It is a powerful application server with many options, although not the most easy piece of software to configure. Still, it provides a viable alternative to proprietary products coming from several industry giants with the ability to make enormous cost-savings. In addition to supporting simple single-instance deployments, JBoss AS can be set-up to work in a clustered environment as well.

It should be noted that following this guide it is possible to run ''multiple'' JBoss AS configurations on top of a same system, provided that different TCP ports are used for each JBoss AS instance.

Operating System Requirements
=============================

Since JBoss AS is a Java-based application, it can be ran on top of many different operating systems. Practically any GNU/Linux distribution is capable of running it without any problems. This guide will be aimed at Debian GNU/Linux. Even though the steps described within this guide will be specific to Debian distribution, it is still possible to make similar deployment on top of any other distribution. The major limitation is the existence of ''start-stop-daemon'' utility on the target distribution in order to utilise the custom-made JBoss AS init.d script presented in this guide.

It is advisable to deploy Debian using the network installation. Additional steps which should be taken to set-up the server properly include setting-up the firewall and remote access, which is outside of the scope of this document. Nevertheless, it should be mentioned that JBoss AS being ran as an unprivileged user (it's at least recommended to do so) usually uses TCP port 8080 for HTTP access, and TCP port 8443 for HTTPS access (in case it is even setup to do so), so it's important to open the appropriate ports in the firewall.

Preparing the Operating System
==============================

Create a separate user for running the JBoss AS:
```
? root
$ adduser --system --group --shell /bin/bash jboss
```

It is advisable not to set the password for the above account in order to disallow direct login. Instead it's better to use sudo for switching to the ''jboss'' user as required.

Since JBoss AS is a Java application, it will be necessary to provide an implementation of JDK. Debian comes with the OpenJDK implementation available by default. It can be installed with:
```
? root
$ apt-get install openjdk-6-jdk
```

Preparing JBoss AS Files
========================

JBoss AS can be obtained from the official homepage. There are currently two stable branches of JBoss AS available for download - the 4.x branch, and the 5.x branch. The 4.x branch is conforming to the Jave EE 1.4 specification, while the 5.x branch conforms to the Jave EE 5 specification. While definitively a later version, the 5.x branch is notably slower in start-up than the 4.x branch. It can take as much as double the time to initialise during boot.

At the time of this writing the latest versions available at the JBoss AS website are 4.2.3GA and 5.1.0GA. Both come in two flavours - JDK 5 and JDK6 variant, each compiled for the particular JDK version.

JBoss installation can be unpacked into any location depending on system administrator's preference. This guide will assume the JBoss AS will be unpacked into /opt.

Upon unpacking the JBoss AS it is advisable to set-up the directory permissions in order to allow only the user and group to access the information within the JBoss AS directory:
```
? root
$ chown -R jboss.jboss /opt/jboss-4.2.3.GA/
$ chmod -R o= /opt/jboss-4.2.3.GA/
```

It might also be beneficial to create a symbolic link to currently deployed JBoss AS instance instead of using the default directory location with a version in the path:
```
? root
$ cd /opt/
$ ln -s jboss-4.2.3.GA/ jboss
```

When running the JBoss AS it is possible to provide the configuration name the JBoss AS will utilise. The different configurations can be thought of as different JBoss AS instances - they come with their own set of separate configuration files, libraries, applications etc. By default JBoss AS comes with three stock configurations - ''minimal'', ''default'', and ''all''. The ''minimal'' configuration, as its name implies, comes with a minimum number of default applications installed. It is very quick to boot, but it also offers less miscellaneous services. The ''default'' configuration comes with a number of default applications like JMX or WebApp Console. It is also the configuration used by default when no configuration has been specified when running JBoss AS through the package-provided run.sh script. The ''all'' configuration comes with many set-up applications, including the applications related to clustering. The configurations can be found in the following location:
```
# /opt/jboss/server/
```

It is highly advisable to leave the default installations intact in order to be able to check for differences made during deployment of various custom applications, using them as a template for all custom deployments. This can be achieved by a simple copy command:

```
? jboss
$ cp -pr /opt/jboss/server/default /opt/jboss/server/custom
```

Deploying init.d Script and Configuring JBoss AS Instance
=========================================================

The init.d script provided with this guide basically implements the same functionality as the package-provided ''run.sh'' script, and is actually based upon it. The major difference is how the options are being assembled, and how the final Java command is being executed (in order to allow proper creation of lock/pid files etc). In addition the script implements stopping of JBoss AS by sending SIGTERM to the appropriate Java process. This way the script is not depending on proper functioning of the JBoss AS service which is utilised by the ''shutdown.sh'' shell script (provided by the package itself as well). The init.d script should be placed in the following location:

```
# /etc/init.d/jboss
```

The permissions for the file should be set as follows:

```
? root
$ chown root.root /etc/init.d/jboss
$ chmod 755 /etc/init.d/jboss
```

The sample JBoss AS init.d configuration file should be placed in the following location (it is necessary to create the ''/etc/jboss'' directory beforehand):

```
# /etc/jboss/jboss.conf
```

It is advisable to have the permissions set for the directory and configuration file as follows:

```
? root
----BEGIN----$
chown root.root /etc/jboss/
chmod 750 /etc/jboss/
chown root.root /etc/jboss/jboss.conf
chmod 640 /etc/jboss/jboss.conf
-----END-----$
```

The above init.d script is a bit peculiar in that it can be used for running multiple instances by creating symlinks within the ''/etc/init.d/'' directory towards it (each symlink representing a separate instance). The script will dynamically use this symlink name in order to determine the instance name and access the appropriate configuration file within the /etc/jboss/ directory. The configuration file name is in the form of ''instance.conf''.

In order to deploy a new instance simply use the following commands and customise the resulting new instance configuration file as appropriate:

```
? root
----BEGIN----$
cd /etc/init.d/
ln -s jboss instance
cd /etc/jboss/
cp -p jboss.conf instance.conf
-----END-----$
```

The configuration file is pretty-much self-explanatory and relates for the most part to ''run.sh'' options. One configuration option which should be taken care with care is the javaOpts option. When JBoss AS is run through its ''run.sh'' shell script, it sets-up the default value for it (by using the ''run.conf'' file from the same directory), so it should be set at least to this value. The default configuration which should be specified for ''javaOpts'' is (as provided with stock run.conf):

```
('-Xms128m' '-Xmx512m' '-Dsun.rmi.dgc.client.gcInterval=3600000' '-Dsun.rmi.dgc.server.gcInterval=3600000')
```

Once the configuration is performed, the init.d script can be used for all the operations like starting the instance, stopping it, or restarting it. In order to add it to the default runlevels, the following command must be issued:

```
? root
$ update-rc.d instance defaults
```