rocketsoftware/uniface repository overview

⁠About the Uniface installation

The Uniface Server Docker Image contains a Linux Uniface Server environment including the Uniface Router and Uniface Server. The purpose of this image is to run Uniface in a containerized Docker environment.

The Docker Image can run in the role of:

• Uniface Application Server
• Uniface Web Application Server (excluding the Web Server)
• Uniface Database Server

The Docker image exposes the Uniface Router process on port 13001 and is used by Uniface to connect from outside the container.

The default user for the Docker image is uniface with password uniface.

These credentials must be used in the Uniface client assignment files to connect to the Uniface Router. It is possible to change the default password for the Uniface user by setting the environment variable AUTH_PASSWORD when the container is started.  

The Uniface Server Docker Image contains the following Uniface files and folders:

⁠About the Docker Base Image

This Uniface Server Docker Image is based on the RedHat Linux Universal Base Image 8 Minimal⁠. Universal Base Images (UBI) are maintained by Red Hat and updated regularly. UBI Minimal is a stripped down image that uses microdnf as a package manager and is freely redistributable. Support for UBI minimal is available through subscriptions for Red Hat products. UBI minimal is designed for applications that contain their own dependencies, like Uniface.

⁠How to use the Uniface Server Docker Image

You configure your Uniface application in the Docker environment by using volume mounts and environment variables.

⁠Create application context with a volume mount

Within the container the Uniface application context is expected at /home/uniface/application. You load application context into the Docker container using a volume mount⁠ from a folder on your host to /home/uniface/application. Your host folder must have an adm sub folder containing the Uniface configuration (ASN and INI files). Additionally, your host folder needs to contain all relevant Uniface application resources (e.g. UAR files).

Within the container USYS Path Logical⁠ USYSADM is set to /home/uniface/application/adm and USYSLOG to /var/log/uniface. At startup, the container will execute the initialization script /home/uniface/unifacerc, change the current directory to the Uniface working directory and start the Uniface Router. The Uniface Router will not start if /home/uniface/application/adm is not present or is mounted incorrectly. For the Uniface Router to start up successfully, /home/uniface/application/adm must contain the following files:

• usys.asn
• urouter.asn
• other relevant Uniface configuration files.

An example of a volume mount in a Uniface Server Docker container: 

/home/uniface/application
├── adm
│   ├── dbms.asn
│   ├── urouter.asn
│   ├── userver.asn
│   ├── usys.asn
├── uars
│   ├── patch.uar
│   ├── application.uar

⁠Create application context with environment variables

In addition to using a volume mount, you can load the following environment variables into the Uniface container:

⁠Configure a Uniface License

An Entitlement which includes the client feature UCTR or server feature USRVCTR is required to use Uniface in docker; your Uniface account manager can arrange this update for you. Configure licensing using the REGTOKEN environment variable if you are using a Cloud LM license, or the LSHOST environment variable if you are using a Sentinel RMS server.

⁠Enable Uniface Logging

By default logging is disabled in the Docker image. To enable logging you have the following options:

1. Standard out. Logs get written to stdout in the container, you can view them with the command 'docker logs'.

   1. You need to set $putmess_logfile /dev/pts/0 in your assignment file.

2. Volume mount. Logs get written to /var/log/uniface.

   1. You need to volume mount this directory to make the logs persistent.

   2. You need to set $putmess_logfile usyslog:userver%p.log in your assignment file

      docker run -v <local log dir>:/var/log/uniface --rm --it rocketsoftware/uniface

3. Docker syslog. Logs get written to stdout in the container, docker forwards them via syslog.

   1. You need to set $putmess_logfile /dev/pts/0 in your assignment file.

      docker run -log-driver syslog --log-opt syslog-address=udp://<ip>:<port> --rm --it rocketsoftware/uniface

All options need $ioprint set in your assignment files.

⁠How to deploy a Uniface application

⁠Deploy a Uniface application with docker run

In this example, the Uniface application context is the local artifacts/application directory. To mount this local directory with a volume mount into the application context of the Uniface Docker image, use the following command:

docker run --rm -p 13001:13001 -v $(pwd)/artifacts/application/:/home/uniface/application/ -e AUTH_PASSWORD='MY$3cr3T' -it rocketsoftware/uniface

⁠Deploy a Uniface application with docker-compose

In addition to using docker run, you can use docker-compose⁠ to start the Uniface backend. Docker-compose uses a YAML-based configuration file for the deployment of one or more containers. Here is an example of a docker-compose.yaml file for deploying the Uniface backend:

---
version: "2.1"

services:
  # The uniface backend
  uniface:
    tty: true # to show logging in docker logs
    image: rocketsoftware/uniface
    container_name: uniface
    ports:
    - 13001:13001
    volumes:
    # to mount the uniface application context (read only) as a folder
    # a sub folder adm is mandatory
    - ./artifacts/application/:/home/uniface/application/:ro
    # to mount the log folder on the host for persistent logging
    # - ./logs/:/var/log/uniface/

If the docker-compose file is properly configured, you can use the following command to start and stop all services defined in the compose file:

# start all services in background (-d)
docker-compose up -d

# show console output of service uniface (-f to remain active)
docker-compose logs uniface -f

# terminate all services
docker-compose down

⁠How to extend Uniface Docker Images 

To use specific database drivers you will need extra Linux packages need to be included in the Docker image. Or you need to change the environment before the Uniface Router is started, for example to update the library loading path. In both cases. you will need to build a new image based on the Uniface base image. To do so, create a Dockerfile⁠. 

⁠Examples

⁠Dockerfile that creates an image with SQL Server packages and odbc.ini

FROM rocketsoftware/uniface

USER root

# Install Miscrosoft SQL ODBC client packages for Uniface MSS 5.3 driver
RUN curl https://packages.microsoft.com/config/rhel/8/prod.repo -o /etc/yum.repos.d/msprod.repo && \
    ACCEPT_EULA=Y microdnf install -y --nodocs msodbcsql17 && \
    microdnf clean all && rm -rf /var/cache/*

#  Copy your ODBC connection settings for SQL Server
COPY odbc.ini /etc/odbc.ini

USER uniface

⁠Dockerfile that creates an image with Postgres packages and odbc.ini

FROM rocketsoftware/uniface

USER root

# Install Postgres 11 ODBC client packages for Uniface PGS 1.3 driver
RUN rpm -ivh https://download.postgresql.org/pub/repos/yum/reporpms/EL-8-x86_64/pgdg-redhat-repo-latest.noarch.rpm && \
    microdnf install -y --nodocs postgresql11-odbc && \
    ln -s /usr/pgsql-11/lib/psqlodbcw.so /usr/lib64/psqlodbcw.so && \
    microdnf clean all && rm -rf /var/cache/*

# Copy your ODBC connection settings for Postgres
COPY odbc.ini /etc/odbc.ini

USER uniface

⁠Odbc.ini for Postgres & SQL Server

[mssql2019]
SERVER = mssql2019
Driver = /usr/lib64/libmsodbcsql-17.so

[postgres11]
; Driver=/usr/pgsql-11/lib/psqlodbcw.so
; next can only be used if there is linked file /usr/lib64/psqlodbcw.so
Driver=PostgreSQL
Database=worktodo
Servername=postgres

⁠Dockerfile that creates an image with Oracle instant client packages and updates the library loading path

FROM rocketsoftware/uniface

USER root

# Install Oracle 18 instant client packages for Uniface ORA 7.3 driver
RUN microdnf install -y --nodocs libaio && \
    rpm -ivh https://download.oracle.com/otn_software/linux/instantclient/185000/oracle-instantclient18.5-basic-18.5.0.0.0-3.x86_64.rpm && \
    ln -s /usr/lib64/libnsl.so.2 /usr/lib64/libnsl.so.1 && \
    microdnf clean all && rm -rf /var/cache/*

# Add Oracle client libraries to the library loading path
RUN echo 'export LD_LIBRARY_PATH=/usr/lib/oracle/18.5/client64/lib:$LD_LIBRARY_PATH' >> /home/uniface/unifacerc

USER uniface

To build your custom Uniface image with your Dockerfile, named myunifaceimage:

docker build . -t myunifaceimage

To use the image myunifaceimage:

docker run --rm -p 13001:13001 -v $(pwd)/artifacts/application/:/home/uniface/application/ -it myunifaceimage