|
|
|
FairCom Technology (which includes FairCom DB, FairCom RTG, and FairCom Edge for purposes of this discussion) is easy to wrap up into a Docker Container. Given that installing FairCom Technology is simply expanding a gzipped tarball on Linux/Unix systems or expanding a .zip file on Windows, FairCom finds that most customers desire to create their own Docker Container from scratch. Therefore, this section provides a few tips to simplify the creation of Docker Containers with FairCom Technology.
Note that we are using the FairCom default ports throughout this section.
Caution! It is not recommended to store application data within a docker container. See Mapping External Folders into Docker.
|
|
|
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 below.
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 to 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.
|
|
|
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).
|
|
|
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.
|
|
|
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.
|
|
|
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.
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
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.
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
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 next section, Mapping External Folders into Docker, shows you how to do this.
|
|
|
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/.
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.
Instead, 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.
For example, 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.
|
|
|
If you cannot connect to the FairCom Server over TCP/IP, you may have port conflicts.
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
Compare the output of netstat to the list provides in Ports Used by FairCom Technology.
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 Ports Used by FairCom Technology.
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 see Mapping External Folders into Docker.
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
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
|
|
|
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.
Below is an example of running a Docker with the -P switch.
sudo docker run -d -P --name edge faircomedge:v3.0.1.206
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.
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.
In the -P example above, Docker maps it to 55005.
In the -P example above, Docker maps it to 55000.
In the -P example above, Docker maps it to 55001.
In the -P example above, Docker maps it to 55003.
In the -P example above, Docker maps it to 55004.
In the -P example above, Docker maps it to 55002.
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.
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 the section, 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. See the screenshot below. Do not change the default value for the SQL port.
