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:
-
Login to Caplin’s Docker registry or your organisation’s local mirror:
docker login docker-release.caplin.com
-
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 Platform Core image.
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>
-
--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:
-
Start a new interactive container called platform1:
docker run --name platform1 -p 8083:8083 -p 18080:18080 -p 18081:18081 -p 15001:15001 -p 15002:15002 -i -t docker-release.caplin.com/platform/core:8.0.5
-
In the container’s interactive terminal, run the command below to start Liberator and Transformer:
./DeploymentFramework/dfw start
-
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. -
Keep the container terminal open for the duration of your development session.
To stop the container, follow the steps below:
-
In the container’s terminal, run the command below to stop Liberator and Transformer:
./DeploymentFramework/dfw stop
-
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>
-
-i: keep STDIN open even if not attached
For example, to restart a container named platform1, follow the steps below:
-
Run the command below to restart the
platform1container:docker start -i platform1
-
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:
docker cp <src_path> <container_name>:<dest_path>
docker cp MyConfigBlade-0.0.0.tar.gz platform1:/app/DeploymentFramework/kits/
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:
docker cp <container_name>:<src_path> <dest_path>
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)
-
Add your own configuration and components
Follow the steps below:
-
Create a new directory, platform-core-dev:
-
Add a licenses sub-directory containing your development licences for Liberator and Transformer:
-
Add a Dockerfile containing the content below:
Dockerfile# syntax=docker/dockerfile:1 FROM docker-release.caplin.com/platform/core:8.0.5 # 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/*.conf /app/DeploymentFramework/global_config/licenses/ # Install extra packages useful for a development image USER root RUN set -ex \ && microdnf -y install less vim wget git unzip \ && microdnf clean all USER platform # Change working directory from '/app' to '/app/DeploymentFramework' WORKDIR /app/DeploymentFramework -
Open a terminal in the root of your project, and run the command below to build the new image:
docker build -t platform-core-dev:1.0.0 .
Don’t forget the period (
.) at the end of the command.
To run an interactive container based on the new image, run the command below:
docker run --name platform-core-dev -p 8083:8083 -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>
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>
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:
# syntax=docker/dockerfile:1
FROM docker-release.caplin.com/platform/core:8.0.5
# 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/licensesExample 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: