Advanced Docker installation

Create an image

When using Docker or Podman containers, some users desire to create their own containers from scratch. This section provides a few tips and best practices to create Docker or Podman containers with FairCom products.

Adding FairCom technology to an image is fairly straightforward. However, FairCom provides a script to facilitate the creation of an essential image identical to the one provided as a gzipped Docker image.

Note: This section uses the FairCom default ports. If you want to use different ports, you can change them in the services.json or ctsrvr.cfg file located in the <faircom>/config folder. Consider changing the image exposed ports accordingly.

 

Use the Docker image creation script

FairCom's provided script, named create_image.sh, helps to create a Docker image starting from a regular FairCom distribution package (gizpped tarball).

Currently create_image.sh supports x64 and ARM64 Linux flavors.

The create_image.sh script relies on some files named Dockerfile* that must reside in the same directory as the create_image.sh script.

The create_image.sh script requires Docker or Podman. Starting with Docker version 24, you may also need to install the Docker buildx plugin in order to correctly support the Docker image creation. Refer to your Docker distribution to know how to correctly install it. 

The create_image.sh script takes the following parameters in this order:

  • FAIRCOM_BUNDLE: this is the first and the only mandatory parameter. This specifies the FairCom gzipped tarball to use as base to create the docker image. The create_image.sh script will take care to select the requested components needed to run the server inside a container based on the image.
  • LICENSE: here the end user can pass a FairCom license file to replace the default license included in the FAIRCOM_BUNDLE. The parameter is optional, if any of the following parameters needs to be passed please specify an empty string “”. Please refer to the samples below.
  • quiet: By default the create_image.sh script creates a backup copy of the configuration folder before creating the image: the quiet parameter will force the create_image.sh script to skip all the questions related to configuration files backup and proceed with the image creation without asking questions. No file will be backed up if the quiet parameter is used.
  • remove: By default the create_image.sh creates a docker image in your local docker instance and saves a copy of it as a gzipped image in the current directory. The remove parameter will force create_image.sh to remove the image from the docker instance and leave only the gzipped image on disk. The gzipped image can be imported in any other docker instance using the docker load command. (Please refer to the “Use provided image section” above to know how to load a gzipped image)

Examples:

Create a simple image starting from a FairCom distribution package:

./create_image.sh FairCom-Edge.linux.x64.64bit.v4.1.3.71.240201.tar.gz

Create an image and replace the default license file with the specified second parameter:

./create_image.sh FairCom-Edge.linux.x64.64bit.v4.1.3.71.240201.tar.gz ctsrvr39481103.lic

Create an image with the default license and skip any question about the saving of the config files:

./create_image.sh FairCom-Edge.linux.x64.64bit.v4.1.3.71.240201.tar.gz "" quiet

Create an image, replace the license with the specified one, and remove the image from the local docker instance:

./create_image.sh FairCom-Edge.linux.x64.64bit.v4.1.3.71.240201.tar.gz ctsrvr39481103.lic "" remove

Create the image with the default license and remove the image from the local docker instance:

./create_image.sh FairCom-Edge.linux.x64.64bit.v4.1.3.71.240201.tar.gz "" "" remove

FairCom generated image details

As FairCom uses create_image.sh to generate the provided docker images, all the images generated with create_image.sh have similar characteristics.

The create_image.sh script takes the following directories from the specified FairCom bundle and puts them in the generated image:

config/
data/
server/
tools/
tranlogs/

Depending on the input package flavor, the script chooses between the provided Dockerfiles to ensure the image exposes the correct default TCP ports. The Dockerfile selects the proper operating system image to host and run the server and to install the required dependencies. It also specifies to start the server when a container based on the image is spawned.

Although FairCom's designed container images have a default location for configuration, data, and tranlogs inside the container, it is a good idea to take advantage of the volume mounts/maps to ensure that configuration, data, and tranlogs are produced outside the running containers to facilitate the upgrade of the image version if needed. See Map external folders into Docker.

FairCom chose the following base operating system images:

  • For X64 platforms (x86_64): Red Hat 8 universal base image
  • For ARM64 platforms: Ubuntu 24.04

 

Create your own Docker image

Some FairCom users prefer to create their own Docker image for various reasons. The most common reason is that complex applications may depend on other software components, which need to be part of the Docker image.

You can create your own Docker image by starting with any image on the Docker hub or using a FairCom-provided image. A FairCom-provided image must be loaded on the Docker host used to generate the new image.

Regardless of the selected base image, the user creating the image should define the image through a Dockerfile. Dockerfiles, together with FairCom's create_image.sh script, can be used as a starting point to create your own Dockerfile that best covers your application needs. 

Usually, a FairCom bundle includes the following:

  • <faircom>/config
  • <faircom>/data
  • <faircom>/server
  • <faircom>/tranlogs

Note: We discuss best practices for storing the config, data, and tranlogs folders in the Copying files into and out of a Docker container and Mapping external folders into Docker sections. As data, transaction logs, and configuration locations depend on your configuration, you might need to change your Dockerfile definition to define and include the correct locations. Map your data, transaction logs, and configuration locations out of Docker containers to facilitate the server binaries updates.

  • Consider adding the ctadmn (administration tool) and ctstop (scriptable command line tool for stopping the FairCom server) into this container. These are both found in the <faircom>/tools folder. FairCom prebuilt Docker images include the entire /tools FairCom distribution folder.
  • In order to take advantage of record compression, the FairCom server must be able to load the zlib library as libz.so. Many Linux-based images distribute zlib as libz.so.1. Make sure your custom image creates a symbolic link to libz.so.1 named libz.so in the same directory where libz.so.1 is hosted so that libz.so.1 is loaded correctly as libz.so. This can be done with a RUN command in your Dockerfile.
RUN ln -s /usr/lib64/libz.so.1 /usr/lib64/libz.soRUN ln -s /lib/aarch64-linux-gnu/libz.so.1 /lib/aarch64-linux-gnu/libz.so

Refer to your base image distribution to understand the name and the path of zlib.

For best performance, include the FairCom client side in the same container as the FairCom server application (faircom). It is possible to host the server and client components in separate containers. However, keep in mind you will experience about a 10-15% performance penalty. This overhead is present if both containers are running on the same machine and using the shared memory communication protocol. If the containers are not on the same machine, and therefore TCP/IP communication is in use, the overhead will be even greater.