Creating the JBossAS Installer

The installer build in the build/install directory creates an IzPack (IzPack Home) installer jar which allows for a more modular installation of the JBossAS server by allowing selection of the various services available to the JBossAS microkernel that make up a J2EE compliant server. In additional, post installation configuration of security and the like will also be supported as the installer improves.

Dependencies

The IzPack installer builder used to create the JBossAS installer has not been completely integrated into the build as yet. Currently you have to install the IzPack installer binaries and point the build/install/build.xml to its location using the izpack.home property. The default location for the property is the build/install/IzPack directory, so if you install to that location there is no need to override its value. In the future the IzPack installer will be pulled from the component repository and install IzPack as needed. There currently is a convenience target called install-izpack that will download the correct IzPack-installer.jar and run it to launch the installer for IzPack.

Building the Installer

To build the installer, first build jboss as usual using the build/build.xml script, and then run the installer target using the build/install/build.xml script. For the ejb3 preview, you need to build  the aspects, ejb3 and ejb3x modules using JDK5 since the ejb3 components are only built if this JDK is seen. Step by step:

  1. Optionally run the install-izpack target if you do not have the IzPack install from the install-cruisecontrol.jboss.com repository. This will download an IzPack-install.jar into the jboss-4.0/build/install directory. Run java -jar IzPack-install.jar to install the installer, and choose and installation location of jboss-4.0/build/install/IzPack or else create a jboss-4.0/build/install/local.properties file with the izpack.home property pointed to your install location.
  2. Point your JAVA_HOME to a jdk1.4.2 installation
  3. Run the main build from jboss-4.0/build to create the base distribution
  4. Point your JAVA_HOME to a jdk5 installation
  5. Rebuild the aspects, ejb3x and ejb3 modules using the jdk5 compiler.
  6. Run the build from jboss-4.0/build/install to create a jboss-4.0.x-installer.jar that contains the (currently jboss-4.0.3-installer.jar). Either the jdk5 or jdk1.4.2 can be used at this point as there is no compilation of classes that will affect the runtime requirements.
The jboss-4.0.x-installer.jar is installed by using java -jar jboss-4.0.x-installer.jar. Any jdk1.4.2+ may be used to run the installer.

The install.xml Syntax

The JBossAS installer is driven by the build/install/install.xml document. This defines the version info, languages, what contents are included into the installer, what panels are displayed during installation. The install.xml document is included into the build.xml as part of the izpack task used in the installer target. The overall structure of the install.xml document is shown in Figure 1.

Figure 1, the install.xml structure.

The main concern is the packs element and its pack children as this defines the contents available for installation. A pack element represents an atomic collection of files that will be installed if the pack is selected. Figure 2 shows the first few pack elements expanded to show typical usage:

Figure 2, pack element examples.
The key pack attributes are:

Internationalization of the PacksPanel

In order to provide internationalization for the PacksPanel, so that your users can be presented with a different name and description for each language you support, you have to create a file named packsLang.xml xyz where xyz is the ISO3 code of the language in lowercase. Please be aware that case is significant. This file has to be inserted in the resources section of install.xml with the id and src attributes set at the name of the file. The format of these files is identical with the distribution langpack files located at $IZPACK HOME/install/langpacks/installer. For the name of the panel you just use the pack id as the txt id. For the description you use the pack id suffixed with ’.description’.

Variables in the install.xml document

There are two types of variable references you will find in the install.xml document: compiler variables and installation variables. A compiler variable looks like an ant macro variable, @{x}. Compiler variables are used when the installer is built, and they are simply the ant properties that exist at the time the installer target is executed. The current compiler variables that are defined include:

Installation variables are variables available during the installation process. These variable are referenced using $x or equivalently, ${x}. These variables are

Built in Installer Variables

Install.xml Installer Variables

You can introduce variables using the installer.xml variables/variable elements in the install.xml document. An example of adding two variables is shown here:

<variables>
   <variable name="custom-variable" value="v1" />
   <variable name="another-variable" value="v2" />
</variables>
Note that In addition, Java system properties are available using a syntax SYSTEM_prop_name where the prop_name is the system property name with '.' replaced with'_'. For example, the java.vendor.url system property would be available as SYSTEM_java_vendor_url

Environment Installer Variables

Environment variables can be accessed via the syntax ${ENV[variable]}. The curly braces are mandatory. Java system properties are available  Example: To get the value of the OS environment variable CATALINA_HOME, use ${ENV[CATALINA_HOME]}.

Customizing Installation Files

The jboss installer listeners added to the installation via the listeners element:

   <listeners>
      <listener
         compiler="org.jboss.install.CompileListener"
         installer="org.jboss.install.PackageListener"
         jar="@{jboss.install}/output/jboss-listeners.jar"
         />
   </listeners>
combine to allow for customization of the installation files based on properties set during installation, based on velocity macro templates described via additionaldata elements in a pack in the install.xml. An example of their use is illustrated by the following jmx-console pack:
   <pack name="jmx-console"
      installGroups="default,all"
      group="JMX"
      required="no">
      <description>An HTML console for the JMX server</description>
      <fileset dir="@{jboss.dist}/server/default"
         targetdir="$INSTALL_PATH/server/default">
         <include name="deploy/jmx-console.war/**"/>
         <additionaldata key="web.xml" value="jmx-console.war/WEB-INF/web.xml.vm" />
         <additionaldata key="jboss-web.xml" value="jmx-console.war/WEB-INF/jboss-web.xml.vm" />
      </fileset>
      <depends packname="war-deployer"/>
   </pack>
Each additionaldata element introduces a key/value pair into a map that is available to the PackageListener when its processing a given pack. The convention used by the PackageListener is that when notified that a file in a pack has been installed, a check of the pack data is made for an entry with a key equal to the file name. For example, when the jmx-console.war/WEB-INF/web.xml is installed, a check for an entry under the key web.xml is made. As seen from the additionaldata element, there is an entry for web.xml, and its value is "jmx-console.war/WEB-INF/web.xml.vm". The value gives the name of a velocity template to search for in the installation. The available velocity templates are defined under the @{jboss.install}/templates directory structure. The "jmx-console.war/WEB-INF/web.xml.vm" value maps to the template @{jboss.install}/templates/jmx-console.war/WEB-INF/web.xml.vm. If a given installation file has a template defined, the template is merged with the existing installation variables, and the output overwrites the original installation file.