Running a USoft application from a Linux container

USoft from a Linux container

USoft delivers a Linux port of the following products:

• RulesService
• Service Framework
• UBlendIt

This allows you to run these products from a Linux container. The Linux container is delivered in the form of a Docker image downloadable from an Azure registry.

usoft.azurecr.io

https://docs.docker.com/storage/

https://docs.docker.com/storage/volumes/

Installing Docker

Download the .exe file for Docker Desktop Installer for Windows from:

https://docs.docker.com/desktop/

This installation includes a Command Line Interface (CLI).

Install by running the .exe file.

Getting a USoft base image from the Azure Container Registry (ACR)

To make USoft deliverables available from a Linux container, you start by pulling a USoft base image. To this base image, you add elements that are specific to your application. From the end result, you create an application-specific image that you make available to end users.

This section describes how you pull a USoft base image as a Docker image from the USoft Azure Container Registry (ACR):

usoft.azurecr.io

From a Powershell or CMD command line, using the syntax below, call the Docker CLI with elevated use ('Run As Administrator’) to pull the image from the registry.

Syntax

docker login --username client-ID --password client-secret
docker pull image
docker logout registry

image     ::=  registry/name:tag
tag       ::=  major.minor[.latest]

The optional addition '.latest' (a literal, not a placeholder) indicates the latest patch of the major.minor version.
Example

docker login usoft.azurecr.io --username 4v81b3q8-0b44-47ez-a8d8-c9a7a6a80616 --password Bzi1X~546yVG27XO7zmxl-5lvjHfmWIeYoUVpc2X
docker pull usoft.azurecr.io/usoft-rulesservice:10.1.latest
docker logout usoft.azurecr.io

Utility links for communicating with Docker

https://docs.docker.com/engine/reference/commandline/login/

https://docs.docker.com/engine/reference/commandline/pull/

https://docs.docker.com/engine/reference/commandline/logout/

Setting up the database connection

In USoft 10.1.1, the USoft rulesservice container only supports connections via ODBC to a SQL Server database. Microsoft ODBC Driver 18 for SQL Server has been pre-installed as part of the image. In the future, Oracle will also be supported.

"odbc.ini” file

On your local Windows system, create folder "C:\ProgramData\USoft", then create a text file named “C:\ProgramData\USoft\odbc.ini". Edit the contents of this file to the following:

Example

[MYSQLSERVER] # Name of the datasource to be used in the RS-config
Driver=ODBC Driver 18 for SQL Server
Server=tcp:host.docker.internal
Database=TRAVEL3
TrustServerCertificate=yes

Syntax

[rs-db-connect-string] # Name of the Data Source Name (DSN) to be used in the RS-config
Driver=ODBC Driver 18 for SQL Server
Server=connection-type:host[,port]
Database=database
TrustServerCertificate=yes

rs-db-connect-string is the data source name by which you will later reference the database instance when you come to configure the Rules Service in the container.

Under Server, connection-type is 'tcp’.

Under Server, the following host name is implicitly available in the container to reference the SQL Server instance on the local host machine on which Docker is running:

host.docker.internal

Under Server, if you do not specify port, the default 1433 port is used.

Database is the name of the database that was created.

The typical connect string format that you use in USoft Binder to access a SQL Server database contains a colon ( : ). The part to the right of this colon corresponds to database:

T940016833\SQLEXPRESS:TRAVEL3

This particular example demonstrates the case where the database is outside the container but on the same machine that hosts the container. Alternatively, the database could run on a remote machine, in the cloud, or even in another container, or in the same container. For USoft it does not matter where the database is located, as long as it is accessible from the Rules Service in the container.

Utility links for setting up database access

On data source specification:

https://www.ibm.com/docs/en/informix-servers/14.10?topic=file-data-source-specification

On port number specification:

https://learn.microsoft.com/en-us/sql/database-engine/configure-windows/configure-a-server-to-listen-on-a-specific-tcp-port

On server specification:

https://learn.microsoft.com/en-us/sql/database-engine/configure-windows/server-network-configuration 

TCP/IP access

Make sure that TCP/IP access to the database is enabled. In SQL Server Configuration Manager, for SQL Server Network Configuration, Protocols for SQLEXPRESS, set TCP/IP = Enabled.

Now in the same location in SQL Server Configuration Manager, identify 1433 as the TCP/IP port through which all incoming clients can access the database.

1433 is the SQL Server default but you may of course have reasons to select a different port number or differentiate between ranges of IP addresses.

In the Windows Services panel, restart the SQL Server SQLEXPRESS service so that it picks up these TCP/IP settings.

Starting the Linux container running the Rules Service

"RulesService-7777.config” file

Before creating a container, create an empty file named "C:\ProgramData\USoft\RulesService-7777.config". (The number 7777 is, of course, just an example.) This file will be used by the Rules Service in the container. This step is not necessary, but it is convenient because it helps not having to configure the Rules Service everytime you create a container.

To make sure that the Rules Service in the Docker container is accessible from outside the container, make the Rules Service port is available when the container is started. The following example creates and runs a container and maps port 7777 on the host machine to port 8101 in the container.

Creating and starting the container

To create and start the container, run the following command line. This will also start the Rules Service in the container. You may have to remove the newlines that we put in for readability.

The -p switches (-p for publish) map port numbers known in the container to port numbers known by the host machine:

• The 8101 port in the container is mapped to the 7777 host port and is used for the Rules Service.
• The 8102 port in the container is mapped to the 8093 host port and is used for the USoft Service Framework.

We need the USoft Service Framework port because, in this article, we make available from the container an entire USoft web application with working webpages. These webpages work because they connect to the Rules Service via a Page Engine service published from the Service Framework. Alternatively, you can mobilise the Service Framework in the same way to publish other types of REST services (for, eg., an end-user REST API to your application) or SOAP services.

docker container run --name "MyUSoftContainer" 
-v "C:\ProgramData\USoft\odbc.ini":/etc/odbc.ini:ro 
-v "C:\ProgramData\USoft\RulesService-7777.config":/opt/usoft/bin64/RulesService-7777.config 
-p 8101:7777 
-p 8102:8093
usoft.azurecr.io/usoft-rulesservice:10.1.latest /opt/usoft/bin64/RulesService -a 7777 -gc host.docker.internal

Open the Docker Desktop program. See that you can view, stop and restart the container from here.

Adding file-based deliverables to the container

To add your application flat file (the application.CON file), the webpages files published from Web Designer, and the Service Framework Java files published from Service Definer, run the following 3 command lines:

docker cp usoft-install-dir\application.con container-name:/opt/usoft/app
docker cp web-designer-publish-dir container-name:/opt/usoft/publish
docker cp service-definer-publish-dir container-name:/opt/usoft/sfw

For example:

docker cp C:\usd10\app\TRAVEL.con MyUSoftContainer:/opt/usoft/app
docker cp C:\usoft\publications\TRAVEL\webpages MyUSoftContainer:/opt/usoft/publish
docker cp C:\usoft\servers\TRAVEL MyUSoftContainer:/opt/usoft/sfw

Configuring the Rules Service

Open a browser and navigate to:

http://localhost:8101/ure.config

To configure,

• At User and Password, enter the database login name and password as per normal.
• At Connection (= the database connect string), enter the rs-db-connect-string that you supplied at the top of the "odbc.ini” file. in the example earlier in this article, this was ‘MYSQLSERVER’.
• At RDBMS, choose odbc.
• At Owner, optionally and as per normal, enter the database owner of the application tables.

Press Next and then:

• At Auto start, make sure you specify Yes. This will ensure that when the container is (re)started, the Rules Service will not only start but will also run with the specified configuration.
• Set Definitions From = Specify Location
• Set Flat File Folder = /opt/usoft/app

Make further settings and click the Next buttons to traverse the configuration wizard as per normal. The Rules Service in the container is configured when you see Engine Connections displayed.

The Rules Service will write all the settings to the "C:\ProgramData\USoft\RulesService-7777.config" file. When the container is destroyed and re-created, the RulesService will use this .config file and will automatically start an engine.

Multiple containers may be started using the same configuration file. Care should be taken when sharing the Rules Service configuration file between multiple containers, because the Rules Service might modify the .config file. It is therefore advised to mount all containers with the read-only option (by adding ":ro"), or else to make sure you use only one of the containers for modifications.

Starting the Service Framework

In this step, we start a USoft Service Framework server (as defined in USoft Service Definer) that makes one or more services available from the container.

In this example, we start a Page Engine service for browsing webpages. In the same fashion, you could start a REST service that offers a REST API to your application, or you could start a SOAP service.

Work from a Docker command line. You can get a Docker command line by running the following command:

docker exec -it container-name bash

For example:

docker exec -it MyUSoftContainer bash

This gives you a command line prompt that looks something like this:

root@cp34543534535:/tmp#

Go to the /opt/usoft/sfw folder inside the container (sfw for Service Framework):

root@cp34543534535:/tmp# cd /opt/usoft/sfw

Run this command to start the Service Framework server:

root@cp34543534535:/opt/usoft/sfw# java --add-opens java.base/java.lang=ALL-UNNAMED -Dlog4j.configurationFile=file:"log4j2.xml" -classpath server-name.jar:lib/*:/opt/usoft/bin64/UService.jar com.usoft.uservice.urest.Main server-name

where server-name is the name of the Server that you defined in Service Definer, for example:

root@cp34543534535:/opt/usoft/sfw# java --add-opens java.base/java.lang=ALL-UNNAMED -Dlog4j.configurationFile=file:"log4j2.xml" -classpath MyServer.jar:lib/*:/opt/usoft/bin64/UService.jar com.usoft.uservice.urest.Main MyServer

Check that you now have both the Rules Service and the Service Framework running by calling up a list a services running in the container:

root@cp34543534535:/opt/usoft/sfw# ps aux

Browsing the solution

You should now be able to test-browse the solution. Open a browser on the machine that hosts the container and the database, and go to:

http://localhost:port-number/service-name/connection-name/

where port-number is the port number in the container mapped to the host port used for the Service Framework (8102 in the example), and service-name and connection-name are the named you defined in Service Definer, for example:

http://localhost:8102/myservice1/myconnection1/