There are two ways to use the FairCom products inside a Docker container:
- Use the gzipped image provided by FairCom
or - Create a Docker image out of a regular package.
A Docker image can be created using the script provided by FairCom or by manually defining your own Docker image.
To install FairCom products into a Docker or Podman container, expand the FairCom product gzipped tarball on Linux systems or a .zip file on Windows into the container.
The following examples center on Docker. However, Docker and Podman commands are interchangeable by simply replacing references to "docker" with "podman". For example, the following command stops a Docker container:
docker container stop edgeAnd the following command stops a Podman container:
podman container stop edgeAll the Docker commands in this document assume the user has enough permissions to run the Docker commands.
If you need assistance configuring your users and groups correctly to run Docker, see the Docker online documentation.
Use the provided image
FairCom provides a Docker image containing the essentials to run the server. This image uses the following naming convention:
FairCom-DB.linux.x64.64bit.v4.1.3.71.240201.DockerImage.tar.gz
FairCom-Edge.linux.x64.64bit.v4.1.3.71.240201.DockerImage.tar.gz
FairCom-RTG.linux.x64.64bit.v4.1.3.71.240201.DockerImage.tar.gzIn order to add the provided image to your host repository, you can use the Docker load command.
docker load < FairCom-Edge.linux.x64.64bit.v4.1.3.71.240201.DockerImage.tar.gzThe FairCom-provided image uses the FairCom product version as the product tag. Optionally, you can tag the imported image with the “latest” tag in order to avoid specifying the entire version tag every time you invoke the image.
docker tag faircomedge:v4.1.3.71 faircomedge:latest
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.jsonorctsrvr.cfgfile located in the<faircom>/configfolder. 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, andtranlogsfolders 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) andctstop(scriptable command line tool for stopping the FairCom server) into this container. These are both found in the<faircom>/toolsfolder. FairCom prebuilt Docker images include the entire/toolsFairCom 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 aslibz.so.1. Make sure your custom image creates a symbolic link tolibz.so.1namedlibz.soin the same directory wherelibz.so.1is hosted so thatlibz.so.1is loaded correctly aslibz.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.soRefer 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.
Start a Docker container
Start the Docker container like any other container using the docker run command. If the image is configured to start the server, the server will start inside the container. FairCom prebuild images and images created with the create_image.sh script use the FairCom server executable as a CMD argument. This means that the container start will initiate the FairCom server startup.
Stop a Docker container
If executing FairCom’s ctstop command does not terminate the Docker container, you can stop the Docker container with the following command:
docker container stop edgeWarning: It is best to stop the FairCom server by executing FairCom’s ctstop command. If this does not work, and the FairCom
COMPATIBILITY TERMINATE_ON_SIGNALkeyword is active inctsrvr.cfg, then using Docker’s stop command works by sending a SIGTERM signal to FairCom server to shut down cleanly. It gives the server ten seconds to shut down. If this is not enough time, the server will be terminated prematurely. This should not result in data loss if your files are under transaction processing control (file modeTRNLOG), but the best practice is to use ctstop. Depending on the docker container network configuration, you might be able to use ctstop from any machine capable of connecting to the running docker container.FairCom prebuild images and images created with the
create_image.shscript use the FairCom server executable as a CMD argument. This means that the server shutdown will cause the container to stop, and restarting the same container will restart the server.
Kill a Docker container
If all other means of stopping the FairCom container fail, you can kill the Docker container with the following command:
docker kill edgeWarning: The warning above in Stopping a Docker container also applies to killing a Docker container.
Copy files into and out of a Docker container
The FairCom server uses various configuration files. It is recommended to copy and maintain these configuration files (from <faircom>/config) to a folder outside the Docker container. This ensures changes to these files are preserved when you replace the current container with a new version of the FairCom Server.
You can use the following techniques to copy any file inside the container to a folder outside the container:
- Before copying files, shut down the Docker container using the following command (adjust your paths accordingly):
docker exec -it edge /opt/faircom/tools/ctstop -auto
- Then run the following docker cp command to copy the
/configfolder to the/tmpfolder:
docker cp edge:/opt/faircom/config /tmp
Docker copies data out of the container into the folder you specify. The command above creates one new folder on your Linux operating system named /tmp/config and copies the container files into it.
- After Docker copies these files, the Linux root owns them. If you want to see and work with these files without being root, you need to change the owner. Run the following command in the folder that contains these files, which in this case is
/tmp. It changes the owner to desired_owner_name. Replace desired_owner_name with your login name or another login name that you want to own these files.
chown -R desired_owner_name config
- To use the new config folder along with any mapped data and
tranlogsfolders (Map external folders into Docker), you must remove the current container and run a new Docker container. Use the following commands to do this:
docker container rm edge docker run -d -p 1883:1883 -p 5597:5597 -p 6597:6597 -p 8080:8080 -p 8081:8081 -p 8443:8443 -v /tmp/:/opt/faircom/data -v /tmp/:/opt/faircom/tranlogs -v /tmp/config/:/opt/faircom/config --name edge faircomedge:v3.0.1.206
The previous command uses these folders on your operating system as the source for config, data, and tranlogs. This ensures your configuration, data, and logs are not lost when you update the Docker container to a new image.
It is a best practice to map another folder besides /tmp to hold your config, data, and tranlogs. The section, Map external folders into Docker shows you how to do this.
Map External Folders into Docker
This section describes best practices for mapping Linux folders into a Docker container.
Warning: Do not run the examples in this section without first reading the entire section and thinking about which Linux folders you want to use to hold your data. Then modify the commands to use your chosen folders.
FairCom stores your data in three folders called data, tranlogs, and config. As described in this guide, for containers based on FairCom prebuilt images and images created with the create_image.sh script, these folders are located inside the Docker container in a folder named /opt/faircom/.
- Data files are stored in
/opt/faircom/data - Transaction Logs are in
/opt/faircom/tranlogs - Configuration files are in
/opt/faircom/config
Note: Storing data inside a Docker container is not a good practice because updating or deleting the Docker container destroys these files. Further, Docker’s internal file system slows down greatly when its files change often.
You should map operating system folders into the Docker container. This stores your data in those mapped folders and preserves your data when you update the Docker image. Use the -v switch in the Docker run command to map operating system folders into Docker’s internal folders.
Example 1. The following command maps the operating system folder named /tmp/data/ into the folder inside the Docker container named /opt/faircom/data/
docker run -d -p 1883:1883 -p 5597:5597 -p 6597:6597 -p 8080:8080 -p 8081:8081 -p 8443:8443 -v /tmp/data/:/opt/faircom/data/ --name edge faircomedge:v3.0.1.206
The -v outside_folder:inside_folder option maps an operating system folder into a Docker container folder. Docker will create the operating system folder if it does not exist. After the command runs, the files and folders in the operating system folder are the only ones visible inside the mapped Docker container folder. Preexisting files and folders stored inside the Docker container’s folder are no longer visible to the applications running inside the Docker container.
FairCom recommends you create your own folders for data, logs, and config files outside the container. After creating these "external" folders, you need to ensure the Docker process has access to these folders. You may need to modify the ownership of these folders to give Docker permission to access them.
chown -R desired_owner_name folder_name
The following folders are possibilities:
/var/lib/faircom/data/var/lib/faircom/tranlogs/var/lib/faircom/config
When creating your own folder for config files, you need to copy a set of FairCom’s config files into /var/lib/faircom/config because the FairCom server will not run without them. For an example of how to do this, see the section, Copying files into and out of a Docker container.
Once these operating system folders are created and the config folder contains FairCom’s config files, you can modify the docker run command with new -v mappings to use those folders. The command below is an example:
docker run -d -p 1883:1883 -p 5597:5597 -p 6597:6597 -p 8080:8080 -p 8081:8081 -p 8443:8443 -v /var/lib/faircom/data/:/opt/faircom/data -v /var/lib/faircom/tranlogs/:/opt/faircom/tranlogs -v /var/lib/faircom/config/:/opt/faircom/config --name edge faircomedge:v3.0.1.206
To find more details about the Docker run command and its parameters, see the Docker online documentation.
Warning: Do not configure two Docker containers to use the same operating system folders for data and tranlogs. If you do, the two instances of the FairCom server will write to the same data files. This can irreparably corrupt the data.
When mapping a configuration folder, always make sure that the
configfolder on the host machine contains the proper configuration files. If no configuration file is found in the mapped configuration folder the server will start in default mode without most of the additional services such as the http services and data produced in the server executable directory.
Troubleshoot TCP/IP port conflicts
If you cannot connect to the FairCom server over TCP/IP, you may have port conflicts. Perform the following checks to troubleshoot:
- When the FairCom server is not running, run the following command to list the ports currently in use on Linux.
netstat – anNote: The
netstatcommand is part of net-tools. If it is not already installed, you can install it using the following command:
yum install net-toolsThe command above is for Red Hat-based Linux distribution images. Refer to your distribution documentation to learn how to install
netstatcorrectly.
- Compare the output of
netstatto the list provided in FairCom ports. If any of these ports are being used by other applications, then the FairCom server will not run properly. You can modify FairCom's configuration files to configure it to use another port. - If you have copied the
configfolder outside the container and mapped that folder back into the container, you can directly edit theconfigfiles using your favorite editor, see Copying files into and out of a Docker container and Map external folders into Docker.
Run a container using -P
If you cannot connect to the FairCom server over TCP/IP, you may have run the Docker container with the -P (upper case P) switch. This switch causes Docker to map the fixed ports inside the Docker container to randomly available ports on the outside of the container.
Example 2. Running a Docker with the -P switch
docker run -d -P --name edge faircomedge:v3.0.1.206Note: If you use the -P switch, you must use Docker’s dynamically assigned port numbers to connect to the FairCom server. This is a convenient way to quickly run multiple containers of the FairCom server on the same computer without port conflicts. On the other hand, it makes it more complicated to connect to FairCom services.
You can run the following command to get the port mappings of a Docker container:
docker port edge
After executing the Docker run command with the -P (uppercase P) example shown above, the Docker container returns port mappings like the following. The results show the mapping of ports from inside the Docker container to the outside.
Example 3. Return
Inside to outside
1883/tcp -> :::55005
5597/tcp -> :::55004
6597/tcp -> :::55003
8080/tcp -> :::55002
8081/tcp -> :::55001
8443/tcp -> :::55000
For example, FairCom uses TCP/IP ports for the following protocols.
-
MQTT uses port 1883 by default.
In the -P example above, Docker maps it to 55005. -
Browser-based apps uses port 8443 by default.
In the -P example above, Docker maps it to 55000. -
MQTT WebSocket uses port 8081 by default.
In the -P example above, Docker maps it to 55001. -
SQL ODBC uses port 6597 by default.
In the -P example above, Docker maps it to 55003. -
ISAM, CTDB, and NAV APIs use port 5597 by default.
In the -P example above, Docker maps it to 55004. - Port 8080 is the insecure HTTP port. Use port 8443 instead.
In the -P example above, Docker maps it to 55002.
You can use FairCom’s config files to change the default ports.
Connect to FairCom's browser-based applications
Note: Use the Google Chrome browser for FairCom browser-based tools. Other browsers may cause unexpected behavior
To connect to FairCom’s browser-based applications, use a URL like the following in your web browser:
https://localhost:8443/Putting this URL in the web browser brings up the landing page for FairCom’s browser-based applications. On this landing page, you can click on the links to run MQTT Explorer, SQL Explorer, and Monitor.
If there are issues:
- Try changing localhost in the URL to the hostname or IP address of the computer running the Docker container containing FairCom. You may also consider using the following URL if localhost is not working:
https://127.0.0.1:8443/
- Try changing 8443 in the URL to the port number that Docker maps to port 8443. In the -P example above, the Docker container maps 8443 to 55000.
Note: SQL Explorer and Monitor applications work properly when using their default ports. Do not change these ports to Docker’s newly mapped ports.
When you launch MQTT Explorer (available in FairCom EDGE), it opens a connection page where you can specify ports for connecting to the application. If you use the -p switch (lowercase p) to run the Docker container, the default ports work without change.
If you use -P switch (uppercase P) to run the Docker container, you need to determine the port that Docker assigned to port 8081, which is the WebSocket port used by MQTT Explorer. In Running a container using -P, its example shows that Docker assigned the external port 55001 to FairCom’s internal MQTT/WS port of 8081. When you log into MQTT Explorer, you must use Docker’s newly assigned external port for the MQTT/WS Port. Do not change the default value for the SQL port.
