Running Liberator on macOS and Windows

Caplin support local deployments of Liberator and Transformer on Windows and macOS for development purposes.

Liberator and Transformer are supplied exclusively as Linux deployment kits from Liberator 7.1.30 and Transformer 7.1.18 onwards. Caplin continue to support Liberator and Transformer on Windows and macOS for local development deployments, but via Linux Docker containers rather than as native Windows and macOS applications.

This page describes how to deploy Linux kits for Liberator and Transformer on a local Windows or macOS development machine.

Requirements

To follow the instructions on this page, you require:

  • Docker Desktop installed and running

  • Caplin’s Platform Core image, available from Caplin’s Docker registry (docker-release.caplin.com) or your organisation’s local mirror.

Running Caplin Platform locally in Docker

Supported platforms: Windows 10, Windows 11, macOS, Linux

Liberator is supported for local development in a Red Hat UBI9 container running in Docker Desktop on Microsoft Windows and macOS. You can either create your own Red Hat UBI9 image from scratch, or use the Platform Core image available from Caplin’s Docker registry (authentication required).

For more information on Caplin Platform system requirements, see Caplin Platform system requirements.

Downloading the Platform Core image

Follow the steps below:

  1. Login to Caplin’s Docker registry or your organisation’s local mirror:

    docker login docker-release.caplin.com

  2. Download the image, replacing <tag> with the version you want to download:

    docker pull docker-release.caplin.com/platform/core:<tag>

For a list of available tags, see the Platform Core release notes.

Starting a new interactive container

To start a new interactive container, use the following form of the docker run command:

docker run --name <container_name> -i -t -p <host_port>:<container_port> ... <image_name>
Options

  • --name: name the container to make it easier to identify later when you want to restart it

  • -i: keep STDIN open even if not attached

  • -t: allocate a pseudo-TTY

  • -p <host_port>:<container_port>: publish a container’s port to the host

For example, to start an interactive container called platform1 that publishes Liberator’s HTTP port (18080), Liberator’s HTTPS port (18081), Liberator’s DataSource port (15001), and Transformer’s DataSource port (15002), follow the steps below:

  1. Start a new interactive container called platform1:

    docker run --name platform1 -p 18080:18080 -p 18081:18081 -p 15001:15001 -p 15002:15002 -i -t docker-release.caplin.com/platform/core:7.1.30

  2. In the container’s interactive terminal, run the command below to start Liberator and Transformer:

    ./DeploymentFramework/dfw start

  3. To confirm Liberator is running, open a web browser and navigate to Liberator’s built-in website http://localhost:18080.

    You won’t be able to login to the Liberator status page or Liberator Explorer until you have configured authentication and authorisation. See Extending the Platform Core image for local development deployments, below.

  4. Keep the container terminal open for the duration of your development session.

To stop the container, follow the steps below:

  1. In the container’s terminal, run the command below to stop Liberator and Transformer:

    ./DeploymentFramework/dfw stop

  2. In the container’s terminal, run the command below to exit and stop the container:

    exit

Restarting an interactive container

To restart a stopped container, use the following form of the docker start command:

docker start -i <container_name>
Options

  • -i: keep STDIN open even if not attached

For example, to restart a container named platform1, follow the steps below:

  1. Run the command below to restart the platform1 container:

    docker start -i platform1

  2. In the container’s interactive terminal, run the command below to restart Liberator and Transformer:

    ./DeploymentFramework/dfw start

Copying a file into a running container

To copy a file into a running container, use the following form of the docker cp command:

Syntax
docker cp <src_path> <container_name>:<dest_path>
Example: copying a deployment kit into a running container
docker cp MyConfigBlade-0.0.0.tar.gz platform1:/app/DeploymentFramework/kits/
Example: copying a license file into a running container
docker cp license-rttpd.conf platform1:/app/DeploymentFramework/global_config/licenses/

Copying a file out of a running container

To copy a file out of a running container, use the following form of the docker cp command:

Syntax
docker cp <container_name>:<src_path> <dest_path>
Example: copying a log file out of a running container
docker cp platform1:DeploymentFramework/servers/Liberator/var/event-rttpd.log .

Removing a stopped container

To remove a stopped container, use the docker rm command:

docker rm <container_name>

Removing a Platform Core image

To remove a Platform Core image, run the docker rmi command:

docker rmi docker-release.caplin.com/platform/core:<tag>

Extending the Platform Core image for local development deployments

The Platform Core image requires customisation before it is useful for local development deployments:

  • Add developer licenses for Liberator and Transformer

  • Reconfigure Liberator authentication and authorisation.

  • Enable Transformer’s PersistenceService (file-based storage)

  • Platform Core <= 7.1.30: install the unzip command

  • Add your own configuration and components

Example 1. Adding licenses and configuring permissioning

In this example, we create a new image based on Platform Core that includes development licenses and is configured with open access (Liberator’s OpenPermissioning blade activated).

Dockerfile
# syntax=docker/dockerfile:1

FROM docker-release.caplin.com/platform/core:7.1.30

# Configure Liberator authentication and authorisation
RUN set -ex \
    && /app/DeploymentFramework/dfw deactivate PermissioningService \
    && /app/DeploymentFramework/dfw activate OpenPermissioning

# Activate Transformer's Persistence Service (file-based storage by default)
RUN set -ex \
    && /app/DeploymentFramework/dfw activate PersistenceService PersistenceServiceClient

# Copy developer licenses
COPY licenses/license-rttpd.conf       /app/DeploymentFramework/global_config/licenses/
COPY licenses/license-transformer.conf /app/DeploymentFramework/global_config/licenses/

# Platform Core <= 7.1.30: install unzip manually
USER root
RUN yum install -y unzip
USER platform

# Change working directory from '/app' to '/app/DeploymentFramework'
WORKDIR /app/DeploymentFramework

We build the image and call it platform-core-dev:1.0.0:

docker build -t platform-core-dev:1.0.0 .

To run an interactive container based on the new image, we run the command below:

docker run --name platform-core-dev -p 18080:18080 -p 18081:18081 -p 15001:15001 -p 15002:15002 -i -t platform-core-dev:1.0.0

Adding a license file to your deployment

The Platform Core image includes 30-minute evaluation licences for Liberator and Transformer.

There are three ways to provide the Platform Core image with your development licenses.

Add a license to a running container

To copy a license into a running container, use the following form of the docker cp command:

docker cp <src_path> <container_name>:<dest_path>
Example 2. Copying a license into a running container

To copy the license file license-rttpd.conf to running container platform1, use the command below:

docker cp license-rttpd.conf platform1:/app/DeploymentFramework/global_config/licenses/

Add a licence when extending the Platform Core image

To add a license when extending the Platform Core image, use the Dockerfile COPY directive:

COPY <src>... <dest>
Example 3. Copying a license when extending Platform Core

The Dockerfile below extends Platform Core and copies two license files from the Dockerfile context to the container’s /app/DeploymentFramework/global_config/licenses/ directory:

Dockerfile
# syntax=docker/dockerfile:1

FROM docker-release.caplin.com/platform/core:7.1.30

# Copy developer licenses
COPY licenses/license-rttpd.conf       /app/DeploymentFramework/global_config/licenses/
COPY licenses/license-transformer.conf /app/DeploymentFramework/global_config/licenses/

Provide licenses via a local filesystem mount

By default, licenses in Platform Core are stored in the container directory /app/DeploymentFramework/global_config/licenses. You can provide licenses at runtime by mounting this container directory on a directory in your local filesystem.

There are advantages and disadvantages to supplying licenses from the local file system:

  • Advantage: you don’t need to change your Dockerfile when the time comes to renew a license.

  • Disadvantage: you should not use this in production environments unless you have a trusted local disk, or persistent storage that you can use to securely hold the license files.

To mount a local directory when running a new container from the command line, use the docker run command’s --mount option, specifying a local directory for the source key:

docker run --mount "type=bind,source=local_dir,destination=/app/DeploymentFramework/global_config/licenses" ...

For more information on the --mount option, see Bind mounts in the Docker documentation.

Alternatively, you can specify a local bind mount in a Docker Compose Compose file. You can provide flexibility by supplying the local directory in an environment variable:

volumes:
    - ${LICENSES_DIR}:/app/DeploymentFramework/global_config/licenses

Example development workflow

For a walkthrough of developing a Java integration adapter using Caplin’s Gradle Project Templates and a local deployment of the Caplin Platform running in Docker, see Developing a Java adapter with Docker on macOS and Windows.

See also: