ONLINE HELP
 WINDEVWEBDEV AND WINDEV MOBILE

Help / WLanguage / Managing databases / HFSQL / Managing HFSQL Client/Server
  • Overview
  • Database and Docker: persistence
  • Step-by-step setup
  • 1. Install Docker
  • 2. Temporarily disable the firewall
  • 3. Create a local volume (directory on the host)
  • 4. Create and execute HFSQL container
  • 5. Re-enable the firewall (firewalld)
  • 6. Query the daemon docker
  • Access to the HFSQL server of the container
WINDEV
WindowsLinuxUniversal Windows 10 AppJavaReports and QueriesUser code (UMC)
WEBDEV
WindowsLinuxPHPWEBDEV - Browser code
WINDEV Mobile
AndroidAndroid Widget iPhone/iPadIOS WidgetApple WatchMac CatalystUniversal Windows 10 App
Others
Stored procedures
HFSQL and Docker
HFSQL Client/ServerAvailable only with this kind of connection
Overview
Docker is a software platform that allows you to run applications in software containers on Linux (Docker runs like a daemon).
Each software container will have its own environment, which simplifies testing and deployment.
Here is the advantage of containers over virtualization: some parties access the "host" server directly (while virtualization creates a "complete" layer of abstraction).
There are many additional tools that complement Docker to manage redundancy, scalability, etc.
As part of the development of an application, Docker makes it possible to isolate each module (the database, the Web server dedicated to Webservices and the Web server dedicated to sites). These different modules can thus be run on the same server while being isolated from each other.
It is also possible to test a container and then implement it under identical conditions.
Notes:
  • Docker is also available for Windows.
  • This purpose of this help page is not to explain how Docker works. However, to use the Docker container that contains the HFSQL server, it is necessary to be familiar with Docker and, in particular:
    • know how to install a new container from the Docker image of the HFSQL server,
    • know how to manage at least one volume required for data persistence,
    • know how to manage the network configuration inside Docker.
  • Only the 64-bit version is available.
Database and Docker: persistence
In its early days, Docker was designed to run "stateless" applications, i.e. without persistent data (data is only temporary and deleted when the container stops). This operating mode would not be very useful for a database.
Since then, Docker has evolved and allows the use of data volumes that are associated with a container (Docker Volume). The data can then be:
  • in a local volume at the Docker host,
  • in a volume on SAN/NAS.
Therefore, it is possible to use an HFSQL database in a Docker container while respecting this division. This keeps the advantage of being able to change the HFSQL container (update, etc.) while keeping the data.
Step-by-step setup
Note: in the following paragraphs, the command lines that illustrate operations on Linux are usable in Ubuntu.

1. Install Docker

First step, the easiest one: installing Docker on the host server.
sudo apt install docker.io

Caution: the name of the application is "docker.io", not "docker" alone.

2. Temporarily disable the firewall

The corresponding statements are:
sudo systemctl stop firewalld
sudo systemctl disable firewalld
sudo reboot
Remark: This temporary deactivation may be necessary to avoid an error when launching the Docker container (causes the error: "Error response from daemon: driver failed programming external connectivity on endpoint HFSQL_DOCKER").

3. Create a local volume (directory on the host)

In order for the data in the database files to be persistent (you want to keep them), it is preferable not to store these files in the container. To do this, a folder is created (or a mount for a SAN/NAS) on the host. In the example below, the folder is created directly on the host's storage.
sudo mkdir /home/docker
sudo mkdir /home/docker/bdd_hfsql
sudo chmod -R 777 /home/docker
Important: in this example of command line, all rights are given on the directory. It is strongly recommended to restrict the rights of the user running the daemon docker as much as possible.

4. Create and execute HFSQL container

At this stage, the daemon docker is installed and the storage volume is created but HFSQL has not yet been installed.
It is actually Docker that will "install" it from its repository site: you just have to indicate to Docker the version to install (all the available versions are available in the "Build Details" tab of the "windev/hfsql" repository on "hub.docker.com".
4.a. Setup "for test"
For testing purposes, it is possible to use the "create" and "start" commands (the command line below has line breaks for more readability).
sudo docker create
--name HFSQL_DOCKER
--volume /home/docker/bdd_hfsql
:/var/lib/hfsql
--publish 4923:4900
windev/hfsql:US230053b
Here are the parameters of the command above:
  • "name": indicates the name of the container.
  • "volume": indicates the "binding" between the volume and the directory defined in the container. In the HFSQL server configuration, the database path will be seen as "var/lib/hfsql".
  • "publish": indicates the container access port (4923 in this example) and the redirection to the port inside the container (4900: HFSQL standard port).
  • the name of the docker package and the HFSQL version (US230053b" in this example).
This command line will cause HFSQL Docker to download the first time. The following information will be displayed in the console (the version number may change):
Unable to find image
"windev/hfsql:US230053b" locally
US230053b: Pulling from windev/hfsql
...
Then, simply start the execution of the container by the command "start":
sudo docker start HFSQL_DOCKER
4.b. Setup "for production"
For a "real" setup, it is necessary to use the Docker "run" command.
sudo docker run -dit
--restart unless-stopped
--name HFSQL_DOCKER
--volume /home/docker/bdd_hfsql
:/var/lib/hfsql
--publish 4923:4900
windev/hfsql:US230053b
In this command line, the parameters are identical to those of the "create" command, plus the restart command.
Tip: the following command allows Docker to start at boot time:
sudo systemctl enable docker
Some notes on the installation:
  • the port provided to the container must be free on the host.
  • the directory of the host (ex: "/home/bob/bdd") must exist and have the necessary permissions.
  • if the server must be accessible from outside the host, the port must be authorized by the host's firewall.
  • only versions validated by our quality department are published on the Docker repository after specific tests. There are no pre-release versions or similar.
Environment variables: When the container is created, if there are no databases, you can define environment variables, for example, via the syntax:
-e HFSQL_RANDOM_PASSWORD=yes
You can use one of the following three variables (or nothing for the default "admin" mode):
  • HFSQL_PASSWORD: Password of the initial account.
  • HFSQL_PASSWORD_FILE: Path of the file that contains the password of the initial account.
  • HFSQL_RANDOM_PASSWORD: The password for the initial account is generated randomly. It is displayed on the standard output and can be found in the logs with the command:
    docker logs HFSQL_DOCKER
You can also use the following variable (optional): HFSQL_USER: Name of the account (admin by default.)

5. Re-enable the firewall (firewalld)

Of course, once the setup is finished, the firewall must be re-enabled if it was disabled in step 2.
sudo systemctl enable firewalld
sudo systemctl start firewalld

6. Query the daemon docker

It is possible to view containers being executed, stop a container, etc.. thanks to the "docker container" command. For example, to list containers being executed:
sudo docker container ls
Access to the HFSQL server of the container
As soon as the container is running, it is possible to access the HFSQL server by indicating:
  • the name of the host server for the server,
  • the port associated with the container as a port for HFSQL (in this article: 4923),
  • the default HFSQL user and password (don't forget to change them).
Note: make sure that the databases created are in the desired volume and not in the container so that they are not lost if the container stops or restarts.
Docker container setups are "dropped": so don't try to find the setup in the WINDEV directory.
The HFSQL Docker container is available at this address: "https://hub.docker.com/r/windev/hfsql/".
Minimum version required
  • Version 22
This page is also available for…
Comments
Click [Add] to post a comment

Last update: 05/26/2022

Send a report | Local help