Skip to main content

Use Docker or Podman with the FairCom server

When using Docker or Podman containers, most customers 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.

Tip

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.

Note

FairCom has found that scripts written for Docker are interchangeable with Podman by simply replacing references to "docker" with "podman". For example, the following command stops a Docker container:

sudo docker container stop edge

And the following command stops a Podman container: 

sudo podman container stop edge

Note

This section uses the FairCom default ports. If you want to use different ports, you can change them in the services.json file.

Create a container

Adding FairCom technology into a container is fairly straightforward.

For FairCom DB V12 (V3 for FairCom RTG and FairCom Edge) you simply copy the following folders into the container:

  • <your FairCom installation folder>/config

  • <your FairCom installation folder>/data

  • <your FairCom installation folder>/server

  • <your FairCom installation folder>/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.

  • You might 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 <your FairCom installation folder>/tools folder.

For best performance, we recommend including the FairCom client side in the same container with 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

Simply start the Docker container like any other container using the docker run command, or script starting the database server engine (faircom.exe on Windows, faircom on Linux/Unix).

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:

sudo docker container stop edge

Warning

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_SIGNAL keyword is active in ctsrvr.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 mode TRNLOG), but the best practice is to use ctstop.

Kill a Docker container

If all other means of stopping the FairCom container fail, you can kill the Docker container with the following command:

sudo docker kill edge

Warning

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 these configuration files (from <your FairCom installation folder>/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:

  1. Before copying files, shut down the Docker container using the following command (adjust your paths accordingly):

    sudo docker exec -it edge /opt/faircom/tools/ctstop -auto

  2. Then run the following docker cp command to copy the config folder to the /tmp folder:

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

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

    sudo chown -R desired_owner_name config

  4. To use the new config folder along with any mapped data and tranlogs folders (Mapping external folders into Docker), you must remove the current container and run a new Docker container. Use the following commands to do this:

    sudo docker container rm edge
sudo 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, Mapping 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 recommended in this guide, 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/
sudo 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.

sudo 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:

sudo 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

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 irrecoverably corrupt the data.

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:

  1. When the FairCom server is not running, run the following command to list the ports currently in use on Linux.

    netstat – an

    Note

    The netstat command is part of net-tools. If it is not already installed, you can install it using the following command:

    sudo yum install net-tools

  2. Compare the output of netstat to 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 configure FairCom to use another port by modifying its configuration files. These ports and files are documented in FairCom ports used by FairCom technology.

  3. If you have copied the config folder outside the container and mapped that folder back into the container, you can directly edit the config files using your favorite editor, see Copying files into and out of a Docker container and Mapping external folders into Docker.

  4. If you have not mapped an operating system folder to the config folder, you use the nano text editor that is built into the Docker container. The config files are located inside the Docker container in the folder /opt/faircom/config. You can use a command like the following to edit a config file. Change some_config_file to the name of the actual file, such as ctsrvr.cfg.

    sudo docker exec -it edge nano /opt/faircom/config/some_config_file

  5. After you change one or more ports in FairCom’s config files, you must stop the FairCom server and remove the container. You can use the following commands to do this. But first modify the run command by changing the appropriate -p option to properly map the new port.

    sudo docker exec -it edge /opt/faircom/tools/ctstop -auto

sudo docker container rm edge


sudo 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

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
sudo docker run -d -P --name edge faircomedge:v3.0.1.206


Note

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:

sudo 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 shown the mapping of ports from inside of 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

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/

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

83138.png

  • For the field named MQTT/WS Port, use the port number that the Docker container maps to 8081. This is FairCom’s MQTT WebSocket port, which allows a web browser to send and receive MQTT messages. In the -P example above, Docker maps this port to 55001.

  • Do not change the SQL Port, which defaults to 6597. This port is used inside the Docker container by FairCom’s app server to connect to the Database Server. Because FairCom’s app server and database server run inside the container, they communicate using their original internal port numbers.