Installing the Deployment Framework

This page provides instructions on how to install the Caplin Deployment Framework, which you can then use to deploy Liberator, Transformer, and integration adapters.

Supported operating systems

For a list of operating systems supported by the Caplin Platform, see Caplin Platform system requirements.

Installation

To install the Deployment Framework, follow the instructions below:

  1. Install Java
  2. Install a Bash shell (Microsoft Windows only)
  3. Unpack the Deployment Framework
  4. Enable dfw command completion
  5. Configure file permissions

Install Java

Oracle Java is required to run Java-based modules of Liberator and Transformer, and to run the majority of integration adapters.

For the specific of the Oracle JDK required by a component, please see the component's installation instructions.

To install Java so that it is compatible with the Deployment Framework, follow the instructions below.

  1. Install the Oracle JDK.

    Choose the JDK that is compiled for the same CPU architecture (32-bit or 64-bit) as the Liberator and Transformer binaries you will be installing.

    Note: Liberator 7 and Transformer 7 binaries for Microsoft Windows are 64-bit and require a 64-bit Java virtual machine (JVM). Liberator 6.2 (and earlier) and Transformer 6.2 (and earlier) binaries for Microsoft Windows are 32-bit and require a 32-bit JVM.

  2. Set the value of the JAVA_HOME environment variable to the installation path for the Oracle JDK.

    Configure the JAVA_HOME environment variable for all shell environments from which you start Caplin Platform components.

For platform-specific help on installing Java and setting the JAVA_HOME variable, see Installing Java.

The Deployment Framework will attempt to locate a Java Virtual Machine (JVM) relative to the path in the JAVA_HOME variable. If the JVM you want to use with the Deployment Framework is not relative to JAVA_HOME, use the ./dfw java command to supply the Deployment Framework with the full path to your JVM.

Install a Bash shell

Microsoft Windows users only. If you are installing the Deployment Framework to Linux or Mac OS, you may skip this step.

For Windows installations, install one of the following two Bash environments:

  • Cygwin. When installing Cygwin, select the following packages in addition to the default packages: unzip, zip, vim, vim-common, ncurses, dos2unix, and wget.
  • The Git Bash shell.

Unpack the Deployment Framework

The instructions below cover how to install the Deployment Framework from the ZIP file available for download from the Customer Download Portal. If you manage the Deployment Framework under source control, follow the instructions in How can I retrieve the Deployment Framework from source control.

To install the Deployment Framework, extract the Deployment Framework ZIP file to a directory of your choice using the unzip command on a Bash command line:

unzip -q -o -a DeploymentFramework-<version>.zip

Important: Always extract the archive using unzip and the options illustrated above. If you use unzip with different parameters, or if you use a different command or GUI application, then the extraction process may fail to extract symlinks and to convert line-endings as intended.

Tip: on Microsoft Windows, to avoid exceeding the Win32 API's maximum path length of 259 characters, extract the Deployment Framework to a directory with a path of no more than 20 characters in length.

Enable dfw command completion

The Deployment Framework includes a script that extends Bash command-line completion to dfw parameters, and sets an environment variable required by Caplin's logcat command.

To enable dfw command completion, see Setting up dfw command completion.

Configure file permissions

Ensure that the user account used to stop and start the Deployment Framework has write permission to the following file system resources:

  • Write permission to the directory (or directories) where log files are written to.
    • By default, logs are written to the var subdirectory in each DataSource component's directory hierarchy, but the location can be overridden for each component with the log-dir configuration item.
  • Write permission to the directory where Liberator's licence-usage database is located.
    • By default, the licence-usage database is located at <dfw-root>/servers/Liberator/users/uupp-rttpd.db, but the default can be overridden by Liberator's uupp-qdbm-name configuration item.
  • Write permission to the directory where Transformer's file-based persistence store is located.
    • This only applies if you have activated Transformer's Persistence Service and you are using file-based persistence.
    • Warning: file-based persistence is not supported for production use.
  • Write permission to the directory where Transformer's Charting Service writes its cache files.
    • This only applies if you have installed Transformer's Charting Service. See the service's charting.conf file for the location of the cache directory.
  • Write permission to the directory where core dumps are written to, or permission to pipe core dumps to the program used to process core dumps.
    • This only applies if the operating system is configured to generate core dumps. See your operating system manual for details.
  • Write permission to the directory where Transformer's memory file is written to.
    • By default, Transformer's memory file is written to Transformer's var subdirectory. The default location can be changed by Transformer's memory-file configuration item.

See also: