1. Installation Guide

Installing the UltraESB is a simple process as it is a standalone Java application. This guide walks you through a fresh installation, starting from scratch, both on Windows and Linux based systems.

However, it is recommended that any serious production deployment is done on a Linux based operating system, as the UltraESB performs best in the Linux environment. For more information on advance production deployments please refer to the Deployment Guide.

The installation guide looks at the following sections for installing the UltraESB

At the end of this guide the UltraESB should be installed and working. The next chapter of the documentation describes the Hello ESB, a Quickstart Guide to get started with running and using the UltraESB for integration.

1.1. Prerequisites

The UltraESB is written in Java, making Java (JDK) the very first requirement. Lets look at the precise requirements you need, to successfully complete the installation.

The requirements for UltraESB can be categorized into two parts, which are the Operating System and the Java Development Kit.

JDK is required, JRE is NOT sufficient
Note that the UltraESB requires a Java Development Kit (JDK), not Java Runtime Environment (JRE), as it uses some tools of the JDK to operate at runtime.

1.1.1. Operating System

The UltraESB works best on a Linux operating system, with a Kernel version 2.6 or later. Since UltraESB is a pure Java application, it will work on a Windows system as well for development use. However, a Linux system is highly recommended for production deployments for multiple reasons including - performance, ease of configuration and tuning of the OS and avoidance of file locking issues etc. Furthermore, commercial production support is only provided against Linux installations. The UltraESB is developed on Ubuntu systems, and load/stress tested on the Amazon EC2 cloud using multiple operating systems. The UltraESB performs slightly better on Ubuntu or Debian systems over CentOS, RHEL or Fedora etc.

1.1.2. Java Development Kit

The UltraESB is currently certified against JDK 1.6.x and 1.7.x. Currently it is developed and tested with the Oracle JDK (previously Sun JDK), and will be supported against the IBM J9 JDK possibly with additional configuration options, to workaround some limitations. Although the UltraESB will work with later versions of Oracle JDK or other JDK implementations, they are currently not certified. Note that whenever there are Sequences that require Java code/fragment compilation, a JDK is required and a JRE will not suffice. Thus the interactive start-up scripts are explicitly configured to look for and use only a JDK.

After installing the JDK, update the "Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files" for the version of the JDK by downloading the policy files from the JDK download page and by replacing the jre/lib/security/local_policy.jar and jre/lib/security/US_export_policy.jar with the versions from the downloaded archive file. The JCE policy file update is required if strong encryption is expected of the ESB during message processing.

Ensure that the JAVA_HOME environment variable points to the JDK home directory, and that the JAVA_HOME/bin directory is on the system PATH. Depending on the operating system, you may have to do this task differently. For a Linux operating system where the JDK has been installed at /opt/jdk directory, you would need to "export JAVA_HOME=/opt/jdk" and "export PATH=/opt/jdk/bin:$PATH" on the command line, or on the /etc/profile or the users’ .bash_rc or .profile file/s.

1.2. Installation

Installing UltraESB is simply downloading and extracting (.zip) the binary distribution, hosted at the downloads page of AdroitLogic, into your software installation directory.

1.2.1. Obtaining the UltraESB

Use your web browser and navigate to the downloads page of AdroitLogic at;

http://www.adroitlogic.org/download.html

Select the binary distribution to proceed with download. An email will be sent with download links for the binary distribution along with additional information.

download
Download link to the binary distribution Download links for the binary distributions are sent ONLY via email. Hence you MUST provide a valid email address.

1.2.2. Installation

On Linux based systems, use unzip command to extract the downloaded binary distribution into your software installation directory (e.g.- /opt).

$ unzip adroitlogic-ultraesb-2.0.0.zip -d /opt/
Note
Extracting the downloaded binary distribution into your home folder is recommended if you are using it for development purposes.

On Windows operating systems right click on the .zip file and extract archive in to "C:\Program Files\" directory.

Given that the prerequisites are met, and above steps are successful, the installation is complete.

Documentation Convention - ULTRA_HOME
Installation archive will be extracted into a directory similar to following, which will be referred to as the ULTRA_HOME.

Linux/Unix

/opt/ultraesb-2.0.0

Windows

C:\Program Files\ultraesb-2.0.0

1.2.3. Structure of the UltraESB installation

Some familiarization of the installation structure will be helpful in using the UltraESB and next chapters of the documentation.

If you are on a Linux based system the tree command will give you something along the structure explained below.

$ tree /opt/ultraesb-2.0.0

If you are on a Windows based system, you can use the File browser to view the installation directory in a tree view.

Note
Order of the directories/files listed below is based on the relevance, and not the alphabetical order.
/bin   
    ultraesb.sh/bat - starts the UltraESB
    uconsole.sh/bat - starts the UltraESB management console
    uterm.sh/bat - starts the UltraESB management terminal
    toolbox.sh/bat - starts the SOA ToolBox
    encrypt.sh/bat - encrypts password to be stored on the configuration file and uconsole shiro users file
    ultraesb-daemon.sh - starts and manages the UltraESB on production deployments (start | stop | etc…)
    uconsole-daemon.sh - work same as the ultraesb-daemon.sh. starts the console as a service
    zkServer.sh/bat - startup script for starting ZooKeeper for UltraESB clustering
    zkCli.sh/bat - command line client for ZooKeeper
    zkEnv.sh/bat - helper script to setup the environment for the zkServer and zkCli
    zkCleanup.sh - cleanup old transaction logs, snapshots of ZooKeeper
    /native - directory containing the wrapper native libraries

/conf      
    ultra-root.xml - the root configuration file that contains the core engine configuration
    ultra-custom.xml - the custom spring beans that are statically included into the root configuration
    ehcache.xml - ehcache configuration for the UltraESB caching implementation, better keep it as it is
    encrypted.properties - phrases for the encrypted information
    log4j.properties - UltraESB loggers configuration
    log4j_zk.properties - ZooKeeper logger configuration
    wrapper.conf - wrapper configuration used by the UltraESB daemon script
    zoo.cfg - ZooKeeper configuration
    /deployments - the directory containing the deployment units
        /default - the default deployment unit
            ultra-unit.xml - the configuration of the default deployment unit which holds proxy service definitions
            /lib - the libraries related to the default deployment unit (this is empty by default as there are no libraries required for the default deployment unit)
            /classes - mediation classes for the default deployment unit
            /src - mediation sources for the default deployment unit
    /monitoring - monitoring related configurations
        ultra-metrics.xml - the metrics engine configuration
        alert-configs.json - the alert configurations defined in a JSON format
        default-alert-actions.json - default alert actions defined for all alerts (alert actions can also be defined per alert configuration)
    /management - management related configurations
        uterm.properties - configurations of the UltraESB management terminal
        log4j_uterm.properties - UltraESB management terminal loggers configuration
        wrapper-uconsole.conf - wrapper configuration used by the Uconsole daemon script
    /mediation
        /classes - default location where mediation sequences are compiled
        /src - default location for any Java source code to be picked up by sequences
    /keys - the Keystores for private keys and certificates

/data - default data directory used by the UltraESB
    /zookeeper - default data directory used by the ZooKeeper

/docs - documentation assets of UltraESB

/lib - ultraesb and other core libraries
    /patches - patches to any of the libraries used by the UltraESB - this location occurs first in the classpath
    /custom - libraries developed or third-party libraries added by the user to be used in sequences etc
    /endorsed - Java endorsed directory for UltraESB
    /optional - contains optional JAR files. Files not used in your installation maybe deleted
    /samples - contains JAR files used in samples. Maybe deleted in a production environment
    /test - contains JAR files used for unit tests. Maybe deleted in a production environment

/logs - default log directory

/samples
    /conf - sample configuration files
    /resources - XSD’s, WSDL’s, XSLT’s etc. used by samples
    /src - source code for samples and unit tests
    /webapp - Web application loaded into the sample Jetty server for samples and unit tests
    /bin - script files for load tests

/tmp - temporary files

/uconsole - uconsole artifacts and web app

/webapp - UltraESB web application, which can be used to install UltraESB on any J2EE container

Above explanation of the directory/file structure of UltraESB installation gives an overview of the UltraESB contents. These files, their content and its use will be described extensively through out the documentation. The installation structure and any customization will be discussed in detail in the Configuration and Administration chapter.

Refer to the Production Deployment Best Practices guide on how to configure the default installation to cater to a production deployment.

With that briefing on the installation content, its time to start Running the UltraESB.

1.3. Install from Source

The UltraESB is an Open Source project which builds a Free Software to use. Free software doesn’t necessarily mean that it is open source. The vital distinction of an open source project from a free software is that the exact same binary distribution that is available for you to use can be built with the relevant source distribution, and that source distribution is available at public, possibly with some restrictions declared by the respective license.

Some organizations prefer to have the software that they run, built from the source themselves, guaranteeing that the binary that they run is safe. This could be enforced by the company policies etc. The UltraESB source distribution is public and available under the OSI approved AGPL license, and it can be used to build the AGPL licensed binary.

1.3.1. Obtaining the UltraESB source

Use your favorite browser and navigate to the downloads page of AdroitLogic, which is;

Select the Source Distribution to initiate download.

source

Now that you have downloaded the source distribution lets look at how we can build the binary distribution from this source.

Latest Snapshot Build
Above instructions are to download the released source distribution. If you want to be on the bleeding edge and want to get a build from the latest development version, you may checkout the source from Bitbucket, using Mercurial.
$ hg clone https://bitbucket.org/adroitlogic/ultraesb

1.3.2. Building the UltraESB from source

On Linux based systems, use unzip command to extract the downloaded source distribution into your software build directory (e.g.- /opt/src).

$ unzip adroitlogic-ultraesb-2.0.0-src.zip -d /opt/src/

On windows based systems right click on the downloaded source archive and extract it to a user directory.

Navigate to the base directory of extracted source from a command line.

$ cd /opt/src/ultraesb-2.0.0-src

Perform a full build of the distribution, without unit tests, using Maven.

$ mvn clean install -Dmaven.test.skip=true

On successful completion of the build you should see a similar output on the console.

build

Use the binary distribution that was built during build process to install the UltraESB.

/opt/src/ultraesb-2.0.0-src/modules/distribution/target/adroitlogic-ultraesb-2.0.0-agpl.zip

1.3.3. Installation

Follow the instructions in Installation section to complete installation.

1.3.4. Maven

The UltraESB source is shipped with Maven build scripts to build the binaries.

Therefore having Maven, and Java (JDK 1.6 or later), installed in build environment is a prerequisite to building the distribution from source.

Download Maven 3.0.x or later from the Maven downloads page, and follow Maven installation instructions to get Maven installed and configured in your environment.

JAVA_HOME
Make sure to set JAVA_HOME environment variable to correct JDK path before executing Maven commands.
Other Maven instructions

Perform a full build of the distribution with unit tests. Any outdated dependencies will be fetched during the build.

$ mvn clean install

Perform a full build of the distribution with unit tests, in offline mode. Offline mode can be used to quicken the build the process.

$ mvn clean install -o

Perform a full build of the distribution without unit tests.

$ mvn clean install -Dmaven.test.skip=true

Perform a full build of the distribution without unit tests, in offline mode.

$ mvn clean install -o -Dmaven.test.skip=true

Back to Home Page