Konfiguration

Die 5Minds Engine lässt sich wahlweise über eine JSON-Konfigurationsdatei oder Umgebungsvariablen konfigurieren, so dass moderne, flexible Entwicklungs- und Betriebsumgebungen wie Docker optimal unterstützt werden.

Die Schlüssel bzw. Namen der JSON-Konfiguration bzw. Umgebungsvariablen sind bei allen Konfigurationsmöglichkeiten explizit angegeben.

Weiter unten auf dieser Seite finden sich eine Beispieldatei für die JSON-Konfiguration sowie eine Beispielkonfiguration für Docker mittels Umgebungsvariablen.

Referenz

Im Folgenden werden die einzelnen Aspekte der Konfiguration erläutert.

Datenbank

Die Datenbanken müssen vor dem Starten der 5Minds Engine hochgefahren werden und erreichbar sein.

Darüber hinaus muss sichergestellt sein, dass innerhalb des Datenbank-Servers die unter database angegebene Datenbank bereits angelegt ist und der unter username angegebene User auf diese Datenbank zugreifen kann. Das Datenbank-Schema und die enthaltenen Tabellen werden dann von der 5Minds Engine beim ersten Zugriff auf die Datenbank automatisch angelegt.

Wie die Datenbank konfiguriert und hochgefahren wird, ist den Dokumentationen der entsprechenden Datenbankmanagement-Systeme zu entnehmen.

Für den Fall das mehrere 5Minds-Engine-Instanzen dieselbe Datenbank benutzen sollen, kann optional ein Schema angegeben werden. Diese werden dem Tabellennamen vorangestellt (schema.tablename).

Microsoft SQL Server

Minimales Beispiel für Microsoft SQL Server:

"database": {
  "dialect": "mssql",
  "host": "localhost",
  "port": 1433,
  "database": "engine",
  "username": "engine",
  "password": "5Minds3ng!ne"
},

Vollständiges Beispiel für Microsoft SQL Server:

"database": {
  "dialect": "mssql",
  "host": "localhost",
  "port": 1433,
  "database": "engine",
  "username": "engine",
  "password": "5Minds3ng!ne",
  "supportBigNumbers": true,
  "resetPasswordRequestTimeToLive": 12,
  "logging": false,
  "schema": "myschema",
  "compressProcessTokens": false,
  "retry": {
    "maxDuration": "60m"
  }
},

PostgreSQL

Minimales Beispiel für PostgreSQL:

"database": {
  "dialect": "postgres",
  "host": "localhost",
  "port": 5432,
  "database": "engine",
  "username": "admin",
  "password": "admin",
},

Vollständiges Beispiel für PostgreSQL:

"database": {
  "dialect": "postgres",
  "host": "localhost",
  "port": 5432,
  "database": "engine",
  "username": "admin",
  "password": "admin",
  "supportBigNumbers": true,
  "resetPasswordRequestTimeToLive": 12,
  "logging": false,
  "retry": {
    "maxDuration": "60m"
  },
  "dialectOptions": {
    "ssl": true
  }
},

SQLite

Minimales Beispiel für SQLite:

"database": {
  "dialect": "sqlite",
  "storage": "engine.sqlite",
}

"database": {
  "dialect": "sqlite",
  "storage": "engine.sqlite",
  "host": null,
  "port": null,
  "username": null,
  "password": null,
  "database": null,
  "supportBigNumbers": true,
  "resetPasswordRequestTimeToLive": 12,
  "logging": false,
  "retry": {
    "maxDuration": "60m"
  }
}

Für den Produktiveinsatz wird die Verwendung eines dedizierten Datenbankmanagementsystems empfohlen.

Komprimierung

Mit dem Schlüssel database/compressProcessTokens bzw. der Umgebungsvariablen database__compressProcessTokens kann eingestellt werden, ob die Process Token Payloads und Data Object Values komprimiert gespeichert werden sollen.

Die Komprimierung erfolgt mit gzip.

Standardmäßig findet keine Komprimierung statt.

Connection Pools

Es gibt 2 verschiedene Möglichkeiten die Größe des Connection Pools zu konfigurieren.

Globales Limit

Mit dem Schlüssel database/pool/max bzw. der Umgebungsvariable database__pool__max kann die maximale Anzahl gleichzeitg offener Datenbankverbindungen festgelegt werden.

bsp:

"database": {
  "pool": {
    "max": 100
  }
}

Die maximal konfigurierten Connections werden gewichtet über drei Engine Prozesse verteilt (External Tasks, Lesende API Requests und Prozessausführung).

Limit pro Engine Prozess

Eine spezifischere Verteilung kann mit den Schlüsseln database/pool/maxForExternalTasks, database/pool/maxForQueryRequests und database/pool/maxForProcessExecution erreicht werden.

bsp:

"database": {
  "pool": {
    "maxForExternalTasks": 30,
    "maxForQueryRequests": 30,
    "maxForProcessExecution": 40
  }
}

Allen Parametern muss ein ganzzahliger Wert zugewiesen werden.

Wichtig: Es müssen alle drei Werte gesetzt werden.

Auch schließen sich die beiden Konfigurationsmöglichkeiten gegenseitig aus. Es kann immer nur eine der beiden Varianten benutzt werden. Sind beide Varianten konfiguriert, wird die Engine den Startvorgang mit einem Fehler abbrechen.

ID

Mit dem Schlüssel application/id bzw. der Umgebungsvariablen application__id kann der Engine eine eindeutige, technische ID gegeben werden, mit der sich die Engine identifiziert.

  "application": {
    "id": "engine-team1"
  },

Name

Mit dem Schlüssel application/name bzw. der Umgebungsvariablen application__name kann der Engine ein individueller, beschreibender Name gegeben werden, mit dem sich die Engine gegenüber dem 5Minds Studio identifiziert.

  "application": {
    "name": "Meine 5Minds Engine"
  },

Default Response Limit

Mit dem Schlüssel application/defaultResponseLimit bzw. der Umgebungsvariablen application__defaultResponseLimit kann die Menge an Einträgen in Antworten der API beschränkt werden.

Dieses Limit betrifft alle Query Endpunkte (z.B. für Prozessinstanzen).

  "application": {
    "defaultResponseLimit": 500
  },

Der Standardwert für dieses Limit ist 1000.

Readyness

Mit dem Schlüssel application/touchFileOnReady bzw. der Umgebungsvariablen application__touchFileOnReady gibt es die Möglichkeit eine onReady-File an einem beliebigem Pfad zu “touchen”, wenn die Engine betriebsbereit ist.

Die Datei kann genutzt wurden, um festzustellen, ab wann die Engine genutzt werden kann:

  "application": {
    "touchFileOnReady": "/tmp/healthy"
  },

Im Docker Container ist die Datei per Default unter /tmp/healthy zu finden. Wenn nichts oder ein leerer String konfiguriert ist, wird keine Datei erstellt.

Extensions

Mit diesen Einstellungen lässt sich gezielt steuern, welche der für eine Engine installierten Extensions beim starten geladen werden sollen.

Beispiel:

  "extensions": {
    "include": ["my_engine_extension_1", "my_engine_extension_2"],
    "exclude": ["my_engine_extension_2"]
  },

include

Mit dem Schlüssel extensions/include bzw. der Umgebungsvariablen extensions__include kann konfiguriert werden, welche Extensions beim Engine Start berücksichtigt werden sollen.

  "extensions": {
    "include": ["my_engine_extension_1", "my_engine_extension_2"],
  },

Extensions in dieser Liste sind somit whitelisted.

exclude

Mit dem Schlüssel extensions/exclude bzw. der Umgebungsvariablen extensions__exclude kann konfiguriert werden, welche Extensions beim Engine Start ignoriert werden sollen.

  "extensions": {
    "exclude": ["my_engine_extension_2"]
  },

Extensions in dieser Liste sind somit blacklisted.

kombiniert

Wenn beide Parameter gesetzt sind, werden nur die Extensions geladen, die:

• Über include whitelisted sind
• nicht über exclude blacklisted sind

Beispiel:

  "extensions": {
    "include": ["my_engine_extension_1", "my_engine_extension_2"],
    "exclude": ["my_engine_extension_2"]
  },

Mit diesen Einstellungen wird ausschließlich die my_engine_extension_1 Extension geladen.

Alle Extensions deaktivieren

Um sämtliche Extensions zu deaktivieren, kann include zu einem leeren Array gesetzt werden.

  "extensions": {
    "include": []
  },

HTTP-Server

Der Server der 5Minds Engine erlaubt den Zugriff auf die Engine mit Hilfe von HTTP.

Mit dem Schlüssel httpServer/host bzw. der Umgebungsvariablen httpServer__host kann der Host, mit dem Schlüssel httpServer/port bzw. der Umgebungsvariablen httpServer__port kann der Port, auf den sich die HTTP-API bindet, festgelegt werden.

  "httpServer": {
    "host": "0.0.0.0",
    "port": 8080
  },

Jeder Release Channel verwendet einen eigenen Standard Port:

docker run --publish 5000:80 5minds/processcube_engine

Cors Origins

Mit dem Schlüssel httpServer/allowedCorsOrigins bzw. der Umgebungsvariablen httpServer__allowedCorsOrigins kann eine Liste von erlaubten CORS-Origins festgelegt werden.

  "httpServer": {
    "allowedCorsOrigins": ["http://localhost:3000", "http://localhost:3001"]
  },

Der Standardwert ist [*], was bedeutet, dass alle Domains/Origins erlaubt sind. Das Setzen auf [] verbietet alle Origins.

HTTP-Client

Bei der Verwendung von HTTP Service Tasks erfolgt eine Verifizierung des HTTPS-Zertifikats des angesteuerten Endpunktes.

Mit dem Schlüssel httpClient/allowUnauthorizedCertificates oder der Umgebungsvariable httpClient__allowUnauthorizedCertificates kann die Verifizierung deaktiviert werden (true), damit HTTPS-Endpunkte mit nicht autorisierten Zertifikaten angesteuert werden können.

  "httpClient": {
    "allowUnauthorizedCertificates": true
  },

Der Standardwert ist false: Zertifikate müssen immer autorisiert sein, nicht autorisierte Zertifikate werden nicht zugelassen.

Windows Certificate Trust Store

Die Nutzung des Windows Certificate Trust Store kann mit dem Schlüssel tls/useWindowsTrustStore oder der Umgebungsvariable tls__useWindowsTrustStore aktiviert (true) oder deaktiviert (false) werden.

  "tls": {
    "useWindowsTrustStore": false
  },

Der Standardwert ist true.

Runtime Expressions

Timeout in Millisekunden

Mit dem Schlüssel runtimeExpressions/timeoutInMiliseconds oder der Umgebungsvariable runtimeExpressions__timeoutInMiliseconds lässt sich die maximale Ausführungsdauer von Runtime Expressions festlegen. Wenn diese überschritten wird, wird der zugehörige Task mit einer Fehlermeldung beendet.

Standardwert ist 60000. Minimum ist 100.

  "runtimeExpressions": {
    "timeoutInMiliseconds": 60000
  },

Worker Thread Pool

Mit dem Schlüssel runtimeExpressions/workerPoolSize oder der Umgebungsvariable runtimeExpressions__workerPoolSize lässt sich die maximale Anzahl der Worker Threads konfigurieren, welche für die Ausführung von Runtime Expressions zur Verfügung stehen.

Standardwert ist 4. Minimum ist 1.

  "runtimeExpressions": {
    "workerPoolSize": 4
  },

Logging

Mit dem Schlüssel logging/minLogLevel oder der Umgebungsvariable logging__minLogLevel kann das minimale Log-Level gesetzt werden.

Es gibt folgende Log Level (in absteigender Priorität):

• error
• warn
• info
• debug
• trace

Folgende Konfiguration beschränkt die Logausgaben auf info-, warn- und error-Logs:

  "logging": {
    "minLogLevel": "info"
  },

Der Standardwert ist debug.

Authority

Die 5Minds Engine benutzt zur Identitäts- und Zugriffsverwaltung die 5Minds Authority .

"iam": {
  "baseUrl": "http://localhost:11560/",
  "allowAnonymousRootAccess": true,
  "rootAccessToken": ""
}

Mit dem Schlüssel iam/baseUrl oder der Umgebungsvariable iam__baseUrl kann die Adresse der Authority hinterlegt werden.

Root Access

Mit dem Schlüssel iam/allowAnonymousRootAccess oder der Umgebungsvariable iam__allowAnonymousRootAccess kann festgelegt werden, dass Benutzer die Engine anonym in vollem Umfang nutzen können.

Mit dem Schlüssel iam/rootAccessToken oder der Umgebungsvariable iam__rootAccessToken kann festgelegt werden, dass Benutzer die Engine durch einen individuellen Access Token in vollem Umfang nutzen können.

Eigene Konfigurationen

Um eigene Konfigurationen nahtlos an die Settings anzuknüpfen, kann der extraInfo Bereich verwendet werden.

In diesem können beliebige EInstellungen vorgenommen werden, welche auch in Runtime Expressions verwendet werden können.

Das kann nützlich sein, um:

• Extensions zu konfigurieren
• Umgebungsspezifische Einstellungen vorzunehmen
• Runtime Expressions umgebungsbedingt auszuführen

Beispiel

Angenommen es existiert eine Extension MyCustomExtension. Über ein Setting soll gesteuert werden können, ob diese Extension aktiviert ist.

Abhängig davon soll ein Payload für einen External Service Tasks konfiguriert werden.

Konfiguration

Folgende Konfiguration wird dafür deklariert:

{
  "extraInfo": {
    "MyCustomExtension": {
      "enabled": true
    }
  }
}

Runtime Expression

Dieses Setting kann nun folgendermaßen genutzt werden:

const extensionBasedPayload = {};
 
if (evironment.MyCustomExtension.enabled) {
  extensionBasedPayload.msg = 'Extension is enabled!';
} else {
  extensionBasedPayload.msg = 'Extension is disabled!';
}
 
return extensionBasedPayload;

Beispielkonfiguration

Eine vollständige Konfiguration kann z.B. so aussehen:

{
  "application": {
    "defaultResponseLimit": 1000,
    "name": "5Minds Engine",
    "touchFileOnReady": ""
  },
  "extensions": {
    "include": ["my_engine_extension_1", "my_engine_extension_2"],
    "exclude": ["my_engine_extension_2"]
  },
  "httpServer": {
    "host": "0.0.0.0",
    "port": "10560"
  },
  "httpClient": {
    "allowUnauthorizedCertificates": true
  },
  "tls": {
    "useWindowsTrustStore": true
  },
  "logging": {
    "minLogLevel": "debug"
  },
  "runtimeExpressions": {
    "timeoutInMiliseconds": 60000,
    "workerPoolSize": 4
  },
  "database": {
    "username": "myusername",
    "password": "mypassword",
    "database": "engine",
    "host": "localhost",
    "port": 1433,
    "dialect": "mssql",
    "supportBigNumbers": true,
    "resetPasswordRequestTimeToLive": 12,
    "logging": false,
    "schema": "myschema",
    "compressProcessTokens": false,
    "pool": {
      "max": 100
    },
    "retry": {
      "maxDuration": "60m"
    }
  },
  "iam": {
    "baseUrl": "http://localhost:11560/",
    "allowAnonymousRootAccess": true,
    "rootAccessToken": ""
  },
  "extraInfo": {
    "myExtensionSettings": {
      "enabled": true
    }
  }
}

Umgebungsvariablen

Für die leichtere Verwendung in Container-Umgebungen, wie bspw. docker compose, kann die 5Minds Engine auch über Umgebungsvariablen konfiguriert werden:

environment:
  application__defaultResponseLimit: 1000,
  application__name: "5Minds Engine",
  application__touchFileOnReady: ""
  extensions__include: "my_engine_extension_1,my_engine_extension_2"
  extensions__exclude: "my_engine_extension_2"
  httpServer__host: "0.0.0.0",
  httpServer__port: "10560"
  httpClient__allowUnauthorizedCertificates": true
  tls__useWindowsTrustStore: true
  logging__minLogLevel: "debug"
  database__username: "myusername",
  database__password: "mypassword",
  database__database: "engine",
  database__host: "localhost",
  database__port: 1433,
  database__dialect: "mssql",
  database__supportBigNumbers: true,
  database__resetPasswordRequestTimeToLive: 12,
  database__logging: false,
  database__schema: "myschema",
  database__compressProcessTokens: false
  database__retry__maxDuration: "60m"
  database__pool__max: 100
  database__dialectOptions__ssl: true # SSL bei PostgreSQL
  iam__baseUrl: "http://localhost:11560/",
  iam__allowAnonymousRootAccess: true,
  iam__rootAccessToken: ""
  extraInfo__myExtensionSettings__enabled: true,