# 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:

- name: The required name of the pack
- required: The required attribute is a required yes/no attribute used to indicate if the pack must be installed.
- id: The id is an optional attribute used to give a unique id to the pack to be used for internationalization.
- preselected: The preselected attribute is an optional yes/no attribute which indicates if the pack is selected for installation by default. The default for preselected is yes.
- group: The group attribute is an optional attribute that assign the pack to a group. The group allows for grouping packs together in the packs selection panel.

## 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:

- jboss.dist : the root of the jboss distribution build (e.g., jboss-4.0/build/output/jboss-4.0.2)
- jboss.build : the root of the build module (e.g., jboss-4.0/build)
- jboss.licenses : the thirdparty licenses directory that contains the various license text. (e.g., jboss-4.0/thirdparty/licenses)
- jboss.thirdparty : the root of the thirdparty directory (e.g., jboss-4.0/thirdparty)
- jboss.docs : the build docs directory (e.g., jboss-4.0/build/docs)
- jboss.install : the root of the build/install (e.g., jboss-4.0/build/install)
- izpack.home : the IzPack installer installation root used to pick up the IzPack jars.

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_PATH : the installation path on the target system, as chosen by the user
- $JAVA_HOME : the JavaTM virtual machine home path
- $USER_HOME : the user’s home directory path
- $USER_NAME : the user name
- $APP_NAME : the application name
- $APP_URL : the application URL
- $APP_VER : the application version
- $ISO3_LANG : the ISO3 language code of the selected langpack.
- $FILE_SEPARATOR : the file separator on the installation system

### 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.