Before you start the installation

Overview of Apama packages

Apama is available in a number of different packages, which contain Apama and a different selection of associated components. There are also some add-on packages that can be overlaid on the core Apama installation to provide specific additions such as documentation or samples. The table below outlines the available packages (it can be scrolled horizontally).

^{1: Windows only.}

^{2: IAF: Integration Adapter Framework.}

^{3: ADBC: Apama Database Connector.}

^{4: DBP refers to the Digital Business Platform that was a collection of multiple products aligned to work together, some of which transferred to IBM in 2024.}

Supported platforms

Before you install Apama, make sure that you are running one of the supported operating system versions. For detailed information, see the Supported Platforms document for the current Apama version. This can be found at Supported platforms.

Ways to install Apama

It is possible to install Apama in different ways, as described below.

Extraction of installation files

Apama can be extracted from .zip files (Windows) or .tar.gz files (Linux) directly to a chosen location on the disk. All included components are extracted to a location relative to this root installation directory.

The compressed packages can be downloaded from the Apama downloads area.

Side-by-side installations

You can install the same Apama version more than once on the same machine. And you can also install several different versions of Apama on the same machine. This may be necessary to test a new version before it is taken over into a production environment. Each version, however, must be installed in a separate directory. For example, when Apama is already installed in a directory named Apama, you can install a second instance of Apama in a directory named Apama2.

Service packs

Service packs and fixes are provided as .zip files and .tar.gz files in the same manner as the releases. To install a service pack or fix, remove the existing installation of Apama that you wish to replace, and extract the service pack or fix in its place in the same directory.

The service pack or fix provides a complete installation and there is no need to install the base release first. The Apama Release Notes may have more information about the end of support for a specific service pack version. Note that the support lifetime for a service pack may be different, depending on the base version on which the service pack is installed.

Docker and Cumulocity images

Cumulocity has a presence on the Amazon ECR Public Gallery image repository. Several images are available for Cumulocity products. Apama offers several runtime images to run instances of the correlator application. These images differ based on which external connectivity features are required. Apama also offers several buildtime images to be used as part of a multi-stage build to deploy Apama projects, corresponding to the runtime images. See https://gallery.ecr.aws/apama/ for the published images.

Alternatively, images for several products, including Apama, may be built from an installation using scripts included in the installation. For more information, see Introduction to Apama in Docker.

Debian

On Debian-based Linux distributions, you can install Apama using the default package management tool. For more information, see Installing Apama using Debian apt.

Community Edition

The Apama Community Edition is a freemium version of Apama that can be used to get familiar with Apama. It does not need a license and therefore has restricted functionality (see also License terms and technical restrictions).

To install the freemium version, choose the apama-*-dev package which best fits your situation, and which comes as a single .zip or .tar.gz file, which is extracted and used directly as with the premium product. The packages are available from the Apama downloads area.

Additional notes

Disk space requirements

The disk space requirements vary, depending on which options you want to install. For a full installation of Apama including the Apama plug-in for Eclipse (Windows only), approximately 2.5 GB of hard-disk space is required with approximately 1.5 GB of hard-disk space consumed. More disk space will be required depending on what applications you develop and deploy.

License file

A license file is required for the full functionality of Apama. See also About Apama license files.

It is possible to install Apama without specifying a license file. In this case, however, the correlator will run with reduced capabilities. See also Running Apama without a license file.

System clock

Apama requires the system clock to move forwards without large jumps, and never move backwards. This applies only to the underlying clock measuring UTC (Coordinated Universal Time) seconds since 1970; daylight saving time and time zone adjustments will not affect Apama’s timers.

Discontinuities in the system clock can result in disconnections and/or unpredictable application behavior, especially with any application-level timeouts. Virtual machine infrastructure can be particularly vulnerable to such clock issues. Consult your virtual machine vendor’s documentation or support for recommendations on how to correctly handle time for the host operating system you are using and ensuring that the virtual machine host’s clock is correctly synchronized.

Outside of virtual machines, we would strongly recommend using the Network Time Protocol (NTP) on both Windows and Linux, and ensuring that system administrators never make manual adjustments to the system clock. NTP’s default configuration is to handle time adjustments by slightly slowing down or speeding up time, avoiding any sudden jumps. The Windows Time service can cause large time jumps and is not suitable.

Persistence database backup

If using correlator persistence, you are recommended to shut down any running correlators and then take a backup of the persistence database before installing any new major or service pack version, or fix, as the persistence database is automatically upgraded when opened using a newer correlator version and cannot be downgraded or then used with the original correlator version.

See also Using correlator persistence.

Windows platform notes

You can only install Apama products on a local hard drive on a Windows system. You cannot install the products on a network-mounted drive.

The port of the Apama dashboard data server must be accessible to the Apama Dashboard Viewer. If you are on a Windows system and the firewall is enabled, unblock network access for this port. The default value for the port is 3278. For security reasons, never change firewall settings such that this port is exposed to untrusted clients.

Important:

If you are going to install on a Windows system, make sure the machine has the latest Windows updates.

Linux platform notes

Apama does not support Security Enhanced Linux (SELinux). This option should be turned off on Linux for Apama to run.

To build the samples and develop applications using the C/C++ API, development tools that are not present in the default installation of the supported platforms must be installed. On all supported Linux platforms, the GCC-C++ package and all its dependencies must be installed. These are typically provided on the installation media as part of your distribution.

If you intend to use the compiled runtime, ensure that the binutils package is installed.

Note that the performance of latency-critical applications can be significantly impacted by the choice of the file system where the correlator writes its log files and/or persistence database. File systems such as ext3, ext4, NFS, ZFS and GFS2 can have surprisingly poor worst-case latency especially when the system is loaded, so for latency-critical applications we would recommend use of XFS where possible.