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.

Sections that apply only if you are setting up a development environment on Microsoft Windows are indicated with a Windows icon ( ).

Supported operating systems

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

Set system clock to UTC

To ease log-file analysis across servers, time zones, and daylight savings transitions, we recommend that you set the system clocks of all hosts in a Caplin stack to UTC.

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.

    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 ( )

This section only applies if you are using Microsoft Windows.

The Caplin Deployment Framework is designed to run in a Bash shell. To run the Deployment Framework on Microsoft Windows, install one of the Bash shells below:

  • Cygwin

  • Git Bash (an MSYS2 shell distributed with Git for Windows)

Bash symbolic links on Windows

The Caplin Deployment Framework makes extensive use of Bash symbolic links. Cygwin and Git Bash (MSYS2) implement Bash symbolic links in one of four ways: so-called 'magic cookie' files (not recognised by Windows), Windows file shortcuts (*.lnk), NTFS junctions, or NTFS symbolic links. Which implementation is used is determined by the Cygwin/MSYS2 configuration option winsymlinks:{lnk,native,nativestrict}:

  • winsymlinks:lnk: Windows file shortcut

  • winsymlinks:native: NTFS symbolic link (with 'magic cookie' file as a fallback on failure)

  • winsymlinks:nativestrict: NTFS symbolic link (no fallback on failure)

Caplin Platform software on Windows requires Bash symbolic links to be implemented as Windows file shortcuts (winsymlinks:lnk).

For more information on how to set the winsymlinks option, see Installing Cygwin and Installing Git Bash.

Installing Cygwin ( )

To install Cygwin, follow the steps below:

  1. Download the Cygwin installer from the Cygwin website.

  2. Run the Cygwin installer and follow the installation instructions on the Cygwin website.

    When prompted by the installer, select the following additional packages: zip, unzip, vim, vim-common, dos2unix, wget, and curl.

  3. After installation, open a Cygwin terminal and run the command below to configure Cygwin to implement Bash symbolic links as Windows file shortcuts:

    echo 'export CYGWIN=winsymlinks:lnk' >> ~/.bashrc
    Alternatively, if you don’t want to set CYGWIN=winsymlinks globally, then you can set it temporarily when unzipping the Deployment Framework. See Installing the Deployment Framework in the first tutorial.

  4. Close the Cygwin terminal

Installing Git Bash ( )

Git Bash is included with Git for Windows. If you already have Git for Windows installed, skip to step 3 in the installation instructions below.

The Git for Windows installer requires you to have a knowledge of common Git configuration options. In case you are not familiar with Git, the instructions below include a list of Git options commonly used by Windows developers in mixed-OS environments. If you have already installed Git for Windows, you do not need to adjust your Git configuration to suit the example options below.

To install Git for Windows, follow the steps below:

  1. Install Notepad++.

    Notepad++ is a better option on Windows than the Git default of Vim if you need to integrate Git with other Windows programs. See the Choosing the default editor used by Git option below.

  2. Run the Git for Windows installer, and select the following Git configuration options when prompted:

    • 'Choosing the default editor used by Git': Use Notepad++

      Notepad++ is a better choice than Vim if you need to integrate Git with other Windows programs.

    • 'Adjusting your PATH environment': Use Git from the Windows Command Prompt

    • 'Choosing the SSH executable': Use OpenSSH

    • 'Choosing HTTPS transport backend': Use the OpenSSL library

    • 'Configuring the line ending conventions': Checkout as-is, commit Unix-style line endings

    • 'Configuring the terminal emulator': Use MinTTY

    • 'Configuring extra options': Enable file system caching and Enable Git Credential Manager

      The extra option Enable symbolic links is not required by the Caplin Platform on Windows. This option configures the git command on Windows to implement Bash symbolic links as NTFS native symbolic links. This option requires Windows 10, local Administrator privileges, and a new group policy entry (SeCreateSymbolicLinkPrivilege).

  3. After installation, open a Git Bash terminal and run the command below to configure Git Bash to implement Bash symbolic links as Windows file shortcuts:

    echo 'export MSYS=winsymlinks:lnk' >> ~/.bashrc

    If you don’t want to set MSYS=winsymlinks:lnk globally in ~/.bashrc (for example, if you’ve set MSYS=winsymlinks:nativestrict for working with Git), then you can set MSYS=winksymlinks:lnk temporarily when unzipping the Deployment Framework:

    $ MSYS=winsymlinks:lnk unzip -qoa DeploymentFramework-<version>.zip

  4. Close the Git Bash terminal

If you added MSYS=winsymlinks:lnk to the file ~/.bashrc in step 3, then the next time you open a Git Bash terminal, Git Bash will warn you that it has automatically created a Bash ~/bash_profile file. You can safely ignore this warning.

Install Microsoft Visual C++ Redistributable for VS 2015 ( )

This section only applies if you are using Microsoft Windows.

The Windows builds of Liberator and Transformer require the Microsoft Visual C++ Redistributable for Visual Studio 2015.

The installer is available at The latest supported Visual C++ downloads on the Microsoft website.

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

    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: