Docker or Podman

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

In 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.gz

The 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

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.

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

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

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

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

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

config/
data/
server/
tools/
tranlogs/

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.

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 edge

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

docker kill edge

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.

This section describes best practices for mapping Linux folders into a Docker container.

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.

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

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.

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.

docker run -d -P --name edge faircomedge:v3.0.1.206

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.

1883/tcp -> :::55005

5597/tcp -> :::55004

6597/tcp -> :::55003

8080/tcp -> :::55002

8081/tcp -> :::55001

8443/tcp -> :::55000

You can use FairCom’s config files to change the default ports.

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.

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.

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