skilja/classificationmonitor repository overview

⁠Quick reference

• Maintained by:
  Skilja GmbH⁠

• Where to get help:
  The Partner Portal⁠ or via email [email protected]⁠

⁠Supported tags and Versioning

Image tags adhere to <major>.<minor>.<patch>.<revision> format.

<major>.<minor>.<patch>.<revision> points to a specific version. <Major>.<Minor> always points to the latest version. This version is compatible with all previous images of the same <Major>.<Minor> version. <latest> always points to the latest version, but such a version might require service and project database schema updates. For loading the latest but compatible version, we recommend to pull a <Major>.<Minor> with

docker pull skilja/classificationmonitor:<Major>.<Minor>

The latest image tag is:

• 8.0⁠

Warning : Breaking Changes with 8.0

• Mandatory inital usage of the Site Management Tool (more info)⁠

(More Information can be found within the provided release notes)

⁠What is Tegra Classification Monitor?

Its main purpose is to view status information for the projects that are currently in production, like processed document volume and recognition quality based on the number of manually corrected documents. In addition, it is used to make decisions about promoting or reverting new revisions of active projects. The monitor can only show projects that are already enabled for online learning.

The service provides a web application used by operators to review classification results, as well as a REST API that can be used to integrate the monitoring features into your custom application.

Classification Monitor is part of the Tegra product suite, which provides services to conduct OCR and to perform classification or extraction tasks. Projects can be created using Designer applications which are available separately, and documents are processed by the corresponding Service containers (e.g. Classification Service⁠).

⁠How to use this image

The following sample shows how to run the Classification Monitor using PostgreSQL:

1. Optionally for using a PostgreSQL database server, install and start a PostgreSQL container:

docker pull postgres:15.1
docker run --rm -v <localpath>:/var/lib/postgresql/data -e POSTGRES_PASSWORD=MyPassword POSTGRES_USER=laera -p 5432:5432 -d postgres:15.1

2. For the Classification Monitor, configure the environment file to use the user and password from above:

OLCLS_SERVICEENDPOINT=http://+:8042
OLCLS_SELFHOSTWEBSITE=true
OLCLS_OLDATABASESERVERTYPE=2     (2 - PostgreSQL)
OLCLS_OLDATABASESERVER=<database-server-name> (the host computer name in case of local docker installation)
OLCLS_OLUSEINTEGRATEDSECURITY=false
OLCLS_OLSQLUSER=laera
OLCLS_OLSQLPASSWORD=MyPassword

OLCLS_PROJDATABASESERVERTYPE=2     (2 - PostgreSQL)
OLCLS_PROJDATABASESERVER=<database-server-name> (the host computer name in case of local docker installation)
OLCLS_PROJUSEINTEGRATEDSECURITY=false
OLCLS_PROJSQLUSER=laera
OLCLS_PROJSQLPASSWORD=MyPassword

3. Pull and start the Classification Monitor image:

docker pull skilja/classificationmonitor
docker run -p 8042:8042 -d --rm --env-file envfile.txt skilja/classificationmonitor

⁠... via [docker-compose]

Example docker-compose.yml for skilja/classificationmonitor:

# This compose file will start a postgres db and the classification monitor at once
# make sure you have a local DB folder created for the postgres db files

services:
  postgres-db:
    image: postgres
    environment:
      - POSTGRES_PASSWORD=postgres
      - POSTGRES_USER=laera
    ports:
      - "5432:5432"
    volumes:
      - ./DB:/var/lib/postgresql/data:z

  Tegra_ClassificationMonitor:
    image: skilja/classificationmonitor
    depends_on:
      - postgres-db
    links:
      - postgres-db
    ports:
      - "8042:8042"
    environment:
      OLCLS_SERVICEENDPOINT: http://+:8042
      OLCLS_SELFHOSTWEBSITE: true
      OLCLS_OLDATABASESERVERTYPE: 2
      OLCLS_OLDATABASESERVER: postgres-db-1
      OLCLS_OLUSESSL: false
      OLCLS_OLTRUSTCERTIFICATE: true
      OLCLS_OLUSEINTEGRATEDSECURITY: false
      OLCLS_OLSQLUSER: laera
      OLCLS_OLSQLPASSWORD: myPassword

      #project database, required

      OLCLS_PROJDATABASESERVERTYPE: 2
      OLCLS_PROJDATABASESERVER: postgres-db-1
      OLCLS_PROJUSESSL: false
      OLCLS_PROJTRUSTCERTIFICATE: true
      OLCLS_PROJSQLUSER: laera
      OLCLS_PROJSQLPASSWORD: postgres
      OLCLS_PROJUSEINTEGRATEDSECURITY: false

      #this disables the need for an existing Authorization-Server
      OLCLS_HASAUTHENABLED: false

Run docker compose up, wait for it to initialize completely, and visit http://localhost:8042/ or http://host-ip:8042 or http://container-ip:8042

Warning: The shown sample compose is running without Authorization! It is strongly recommended to use authorization in order to protect the service (licenses) and data that might be stored during processing (documents). Here you can find more information about the Authorization Server⁠. The option to use API Keys will also be enabled once you connected the Authorization Server.

⁠HTTPS

You probably noticed that the described sample is not using an SSL certificate. The currently recommended way is to use a Reverse Proxy like NGINX or Traefik.

⁠Supporting Modules

• Authorization Server⁠ to provide single sign-on (SSO) for the classification monitor.

• Classification Service⁠ is required to process the documents that are reviewed within the Classification Monitor.

⁠Service User

Beginning with version 8.0 the used service user is changed to be uniform across all Skilja containers. For .NET based containers like this one, the UID/GID 1654 is now used. This is a non root user called 'app'. This becomes important when working with Volume Mounts.

⁠Site Mangement Tool

When the Classification Monitor is started for the first time, users do not have any permissions assigned by default.
For the first configuration please start the Site Mangement Tool⁠. This step is only required to initially assign the Site Admin and Org Admin roles for the installation. The same initialization step is also required for the following components:

• Classification Designer⁠
• Tegra Classification Service⁠
• Extraction Designer⁠
• Extraction Monitor⁠
• Tegra Extraction Service⁠

(AI Server is currently using its own builtin Site Mangement Tool and is therefore excluded)

For that reason, it is recommended to complete the full installation first and then run the Site Management Tool once to configure all components together.

⁠Environment Variables

The classificationmonitor image uses several environment variables, of which some are required others are optional.

⁠OLCLS_SERVICEENDPOINT

The environment variable OLCLS_SERVICEENDPOINT sets the URL where the classification monitor is exposed locally on the computer. This parameter is ignored when the service is hosted inside the IIS.

⁠OLCLS_PATHBASE

When not empty, the environment variable OLCLS_PATHBASE (PathBase) allows the application to be hosted at the desired base path. This may be necessary when running behind a reverse proxy or in containerized environments. When the base path is configured, the application still continues to be hosted at the root path as well.

For example, to make the application accessible for clients and services at http://server.com/classificationmonitor⁠, set the path base to "classificationmonitor". This parameter is ignored when the Web designer is hosted inside the IIS.

⁠OLCLS_OLDATABASESERVERTYPE

The environment variable OLCLS_OLDATABASESERVERTYPE sets the database server type to connect to as integer for the Classification Monitor database.

- 0 - SQL Server
- 1 - Oracle database
- 2 - PostgreSQL

⁠OLCLS_OLDATABASESERVER

The environment variable OLCLS_OLDATABASESERVER defines the database server name that hosts the Classification Monitor database.

⁠OLCLS_OLUSESSL

The environment variable OLCLS_OLUSESSL defines whether to use SSL on the Classification Monitor database connection or not. This is currently supported for MS SQL server and PostgreSQL server.

⁠OLCLS_OLTRUSTCERTIFICATE

The environment variable OLCLS_OLTRUSTCERTIFICATE is only relevant when UseSSL is true. By default the SSL certificate must be officially signed. Set this parameter to true for self-signed SSL certificates that are not officially trusted.

⁠OLCLS_OLDATABASENAME

The environment variable OLCLS_OLDATABASENAME sets the database name for the Classification Monitor database.

⁠OLCLS_OLUSEINTEGRATEDSECURITY

The environment variable OLCLS_OLUSEINTEGRATEDSECURITY set to true, uses integrated security for database access. When set to false, it uses SQL user and password.

⁠OLCLS_OLSQLUSER

The environment variable OLCLS_OLSQLUSER sets the SQL user name if integrated security is false.

⁠OLCLS_OLSQLPASSWORD

The environment variable OLCLS_OLSQLPASSWORD sets the SQL password if integrated security is false.

⁠OLCLS_AUTOCREATEDATABASE

The environment variable OLCLS_AUTOCREATEDATABASE set to true, causes the Classification Monitor database to be created automatically. Otherwise, the database is not created.

⁠OLCLS_PROJDATABASESERVERTYPE

The environment variable OLCLS_PROJDATABASESERVERTYPE defines the database server type to connect to as integer for the Classification Web Designer database.

Same values as in: OLCLS_OLDATABASESERVERTYPE

⁠OLCLS_PROJDATABASESERVER

The environment variable OLCLS_PROJDATABASESERVER defines the database server name that hosts the Classification Web Designer database.

⁠OLCLS_PROJUSESSL

The environment variable OLCLS_PROJUSESSL set to true uses SSL encryption on the Classification Web Designer database connection. This is currently supported for MS SQL server and PostgreSQL server.

⁠OLCLS_PROJTRUSTCERTIFICATE

The environment variable OLCLS_PROJTRUSTCERTIFICATE is only relevant when UseSSL is true. By default the SSL certificate must be officially signed. Set this parameter to true for self-signed SSL certificates that are not officially trusted.

⁠OLCLS_PROJDATABASENAME

The environment variable OLCLS_PROJDATABASENAME defines the database name for the Classification Web Designer database.

⁠OLCLS_PROJUSEINTEGRATEDSECURITY

The environment variable OLCLS_PROJUSEINTEGRATEDSECURITY set to true, uses integrated security for Classification Web Designer database access. When set to false, it uses SQL user and password.

⁠OLCLS_PROJSQLUSER

The environment variable OLCLS_PROJSQLUSER sets the SQL user name if integrated security for the Classification Web Designer database is false.

⁠OLCLS_PROJSQLPASSWORD

The environment variable OLCLS_PROJSQLPASSWORD sets the SQL password if integrated security for the Classification Web Designer database is false.

⁠OLCLS_SELFHOSTWEBSITE

The environment variable OLCLS_SELFHOSTWEBSITE set to true means that the Classification Monitor site is self-hosted, otherwise, it's not hosted automatically.

⁠OLCLS_HASAUTHENABLED

The environment variable OLCLS_HASAUTHENABLED set to true enables authentication for the Classification Monitor. Users need to log in via the configured Authorization Server and need to have access permissions with corresponding roles. Custom applications need to provide an API key with each API call. If this property is false, no authentication and no API keys are required.

⁠OLCLS_AUTHSERVERURL

The environment variable OLCLS_AUTHSERVERURL defines the URL of the Authorization Server if authentication is enabled.

⁠OLCLS_WEBAPPCLIENTID

The environment variable OLCLS_WEBAPPCLIENTID sets the client ID of the web application that is registered as a public client within the Authorization Server.

⁠OLCLS_SERVERCLIENTID

The environment variable OLCLS_SERVERCLIENTID sets the client ID of the server side application that is registered as a confidential client within the Authorization Server.

⁠OLCLS_SERVERCLIENTSECRET

The environment variable OLCLS_SERVERCLIENTSECRET sets the client secret corresponding to the client ID of the server side application.

⁠Oracle connection modes

For Oracle databases, the basic connection mode and TNS connection mode are supported. In basic connection mode, the database server name is the actual computer that hosts the Oracle database. In TNS connection mode, the connection is configured in a separate file that is usually deployed to each client by the Oracle database administrator. This file is named TNSNAME.ORA and there are different ways how the file gets located. The TNSNAME.ORA is searched within a directory defined by the TNS_ADMIN or ORACLE_HOME environment variable. If a TNS configuration file exists, the value for the database server is evaluated as a network alias defined in that file.

Please note that for Oracle the user name and the database name must be identical. Using different values for user name and database name is not fully supported. The integrated security flag is currently not supported for the connection to Oracle databases; a database user and password must always be specified.

Please visit the Online Documentation⁠ for more information.

⁠Other Platforms

The service is also available for Windows installation. Please visit The Partner Portal⁠ or write us an email [email protected]⁠ for more information.