Show only results for:












Deployment

Prequisites

  • Docker or Podman (to run the Toolkit Docker image)
  • SQL Server (to host the database)
  • Keycloak (for authentication and authorization)
  • Optional: Microsoft Exchange (for email integration)
  • Optional: Azure Blob Storage account (if using Azure for blob storage)
  • Optional: Nginx or Apache (if using a reverse proxy)
  • Optional: Cron (for scheduled tasks, e.g. email polling)
  • Optional: PowerBI account (for PowerBI integration)

Docker/Podman

Toolkit is a Docker container with a set of apps for UniversalPlantViewer such as Tickets/Punchlist, Clashes, Lockout/Tagout, and Redlining. You can pull the Toolkit using Docker:

docker pull quay.io/caxperts/toolkit:latest

or (for the latest stable release)

docker pull quay.io/caxperts/toolkit:stable

Database

The application requires a running SQL Server for its database. Migration scripts are provided that are used to populate the database schema.

Local or Azure blob storage

Admin can specify an environment variables that will change how the application saves blobs. Those variables are:

  • STORAGE_TYPE - accepts only 2 values, “local” or “azure”.
  • STORAGE_PATH - when “local” type used, defines an absolute path to storage on the hardware the server is run, e.g. “/home/user/localStorage”.
  • AZURE_STORAGE_CONNECTION_STRING - connection string given by Azure Blob Storage.
  • AZURE_STORAGE_CONNECTION_DOMAIN - the domain defined by Azure Blob Storage.

Reverse Proxy Setup

When configuring a reverse proxy like Nginx or Apache, you must increase the size of headers that can be passed to accommodate larger requests. Below is an example configuration snippet for Nginx to achieve this:

server {
...
proxy_buffers 16 16k; # Sets 16 buffers of 16KB each

proxy_buffer_size 32k; # Increases the initial buffer size to 32KB

proxy_busy_buffers_size 64k; # Sets the busy buffer size to 64KB
...
}

Keycloak Clients and Scopes Setup

To integrate with Keycloak, you need to configure a custom client and associated scopes. Below are the step-by-step instructions for setting up the client and its scopes.

Create a client scope named groups with the following settings:

Scope Settings

  • Name:
  • Description:
  • Type: None
  • Protocol: OpenID Connect
  • Display on Consent Screen: On
  • Consent screen text: if required
  • Include in Token Scope: On
  • Display Order: Leave empty

Mappers

  1. Add a predefined mapper.
  2. Select the “groups” mapper to include group information in the token.

Scope Details

  • Leave empty by default unless specific mappings are required.

Client Configuration

Create a custom client in Keycloak with the following settings to suit your application’s needs.

General Settings

  • Client Type:
    • Leave as default or select “OpenID Connect” if prompted.

Capability Configuration

  • Client Authentication:

    • Off (If confidential access required mark it True)

  • Authorization:

    • Enable or disable based on the client’s specific requirements.

  • Authentication Flow:

    • Standard Flow: Enabled
    • Direct Access Grants: Enabled
    • Enable additional flows as needed based on your use case.

Login Settings

  • Root URL:
    • Leave empty.
  • Home URL:
    • Leave empty.
  • Valid Redirect URIs:
    • https://your.domain.com/* (Adjust to match your domain and paths).
  • Valid Post-Logout Redirect URIs:
      • (Use defaults or specify custom URIs as required).
  • Web Origins:
      • (Use defaults or specify allowed origins explicitly).### Client Scopes Configuration

Cron Setup for Email Polling

The application uses cron as an auxiliary tool to poll for new emails every minute. It checks the mailbox specified by the SUPPORT_EMAIL environment variable. The relevant environment variables are these: AZURE_AD_TENANT_ID, SUPPORT_EMAIL, SUPPORT_CLIENT_ID and SUPPORT_CLIENT_SECRET. For detailed support in this, please contact us directly. If the toolkit should also be able to send (i.e. not only receive) notifications, the a Keycloak client is required (i.e. SERVICE_CLIENT_ID and SERVICE_CLIENT_SECRET as described in the following section).

Setup for Keycloak role sync for with Service Client

To synchronize roles from Keycloak with Toolkit (and also to send notifcations by email), a service client is required. This service client is triggered with the Keycloak group sync cron job. The schedule of this cron job is defined in KC_GROUP_SYNC_CRON.

Creating the service client in Keycloak

  1. Navigate to tab ‘Clients’

  2. Create a new client:

  3. General Settings:

    • Client Type: OpenID Connect
    • Client ID: provide client id name that you want to use
    • Name: Optional
    • Description: Optional

  4. Capability config:

    • Client authentication: ON
    • Authorization: OFF
    • Only Service accounts roles is checked

Adding Groups scope to service client

  1. Navigate to tab ‘Clients’

  2. Choose your newly created client Here named “serviceclient”: Keycloak Panel for service client

  3. Navigate to tab ‘Client Scopes’

  4. Add client scope

  5. Find in scopes the following:

    • Name: ‘groups’
    • Protocol: ‘OpenID Connect’

  6. Add groups scope as ‘default’

Assigning account roles to ‘hidden’ user created by service client

  1. Navigate to the newly created client id.

  2. Navigate to ‘Service accounts roles’ tab.

  3. Assign the service account roles as specified in the picture below:

Keycloak service client privileges

Keycloak service client in environment variables

SERVICE_CLIENT_ID is your service client name, SERVICE_CLIENT_SECRET can taken from the “Credential” tab, labelled Client secret.

Comprehensive Environment Variables List

NEXTAUTH_SECRET = “any_string_that_represents_secret” // required by nextauth to secure authentication via application

DATABASE_URL = :;database=;user=;password=trustServerCertificate=true

DEVICE_ID = e.g. AppControls-upvappcontrol.com, Displayed to UPV when authenticating

KEYCLOAK_BASE_URL = e.g. https://cax.authupv.com

KEYCLOAK_ID = e.g. connector

KEYCLOAK_ISSUER = e.g. https://cax.authupv.com/realms/apps-demo

KEYCLOAK_REALM = e.g. apps-demo

KEYCLOAK_REDIRECT_URL = e.g. https://upvappcontrol.com

LOGIN_HEADER = e.g. CAXperts

NEXTAUTH_URL = e.g. https://upvappcontrol.com

POWERBI_LOGO = it will be displayed on powerbi page

SIGNATURE_REPORT_THRESHOLD = e.g. 1536, represents image size threshold in bytes to filter low quality signature like “dot”

STORAGE_PATH= e.g.”/home/user/testStorage”

STORAGE_TYPE= takes value of “local” || “azure”

AZURE_STORAGE_CONNECTION_STRING = // connection string given by Azure Blob Storage.

AZURE_STORAGE_CONNECTION_DOMAIN = e.g. caxperts.blob.core.windows.net // the domain defined by Azure Blob Storage.

NEXT_PUBLIC_TICKET_PREFIX=“PI-”

REDIRECT_WEBSERVICES_URL=“”

AZURE_AD_TENANT_ID=““000000-0000-0000-0000-000000000”

SUPPORT_EMAIL=“@”

SUPPORT_CLIENT_ID=“000000-00-0000-0000-000000000”

SUPPORT_CLIENT_SECRET=“your_secret”

SERVICE_CLIENT_ID=“” // Keycloak client id created specifically for cron

SERVICE_CLIENT_SECRET=“” // Existing keycloak client secret.

ENABLE_CRON= // ‘true’ if you want cron job to be running, otherwise leave it empty or ‘false’

KC_GROUP_SYNC_CRON=0 3 * * * // this variable is used to run the user admin roles sync every day at 3 am.

PORT=3000

HOST=0.0.0.0

POWERBI_TENANT_ID=

POWERBI_CLIENT_ID=

POWERBI_SECRET=

Browser Authentication in UPV Mode

By default, when the Toolkit runs inside the UPV application, it uses UPV’s authentication context for single sign-on. However, this can be incompatible with reverse proxies like Azure EasyAuth that handle authentication at the HTTP level.

Environment Variable

To enable browser-based authentication even when running inside UPV, set:

USE_BROWSER_AUTH_IN_UPV=true

Behavior

  • Default (USE_BROWSER_AUTH_IN_UPV=false or unset): UPV uses in-app authentication context
  • Enabled (USE_BROWSER_AUTH_IN_UPV=true): UPV uses browser authentication flow (same as web browser)

Use Cases

This flag is particularly useful for:

  • Azure EasyAuth Integration: When placing Azure App Service EasyAuth in front of the application
  • Corporate Proxy Authentication: When authentication is handled by enterprise reverse proxies
  • Centralized Identity Management: When all authentication should flow through a single identity provider endpoint

Configuration Example

For Azure App Service with EasyAuth:

# Enable browser auth in UPV
USE_BROWSER_AUTH_IN_UPV=true

# Standard Keycloak configuration (same as browser deployment)
KEYCLOAK_ID=your-client-id
KEYCLOAK_SECRET=your-client-secret
KEYCLOAK_ISSUER=https://your-keycloak-server/realms/your-realm

Testing

  1. Deploy with USE_BROWSER_AUTH_IN_UPV=true
  2. Open the application in UPV
  3. Verify that clicking “Sign In” redirects to browser authentication instead of opening UPV authentication dialog
  4. Confirm that authentication works through your proxy/EasyAuth setup

Breaking Change

  1. When using STORAGE_TYPE=local with mapped container volume:
    • Please make sure that the mapped volume is owned by user 1000. Otherwise, on blob saving ‘permission denied’ will be raised.