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"
  }
},

SQLite

Minimales Beispiel für SQLite:

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

caution

SQLite wird nur für die Nutzung in Entwicklungsumgebungen empfohlen.

Vollständiges Beispiel für 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 (ExternalTasks, 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.

info

Die Datei wird exakt einmal - nachdem das Resuming angestoßen und alle Extensions gestartet wurden - erstellt/modifiziert und dient daher ausschließlich als Indikator zur initialen Betriebsbereitschaft und nicht etwa als kontinuierlicher Health-Check.

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
  },

Der Standardwert für den Port ist 10560 (für die Beta-Version 10570).

tip

In der Docker-Variante ist der Port innerhalb des Containers immer auf 80 festgesetzt (auch in der Beta-Version).

Hierdurch kann der Port leicht auf einen gewünschten Port, bspw. 5000, veröffentlicht werden:

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

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
  },

ACHTUNG

Diese Konfigurationsform ist für einen Produktionsbetrieb aus Sicherheitsgründen nicht geeignet!

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.

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

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/",
  "clientId": "atlas_engine",
  "clientSecret": "atlas_engine",
  "scope": "test_resource",
  "minimumTokenLifetimeInMs": 60000,
  "allowAnonymousRootAccess": true,
  "rootAccessToken": ""
}

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

Mit dem Schlüssel iam/minimumTokenLifetimeInMs oder der Umgebungsvariable iam__minimumTokenLifetimeInMs kann festgelegt werden, dass der DelegationToken vor dem Verlassen der Engine noch mindestens diese Gültigkeitsdauer in Millisekunden besitzt. So kann sichergestellt werden, dass der Token z.B. auch bei länger laufenden ExternalTaskWorkern nicht ausläuft.

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.

ACHTUNG

Aus Gründen der leichteren Zugänglichkeit ist dieser Wert standardmäßig auf true gesetzt.

Diese Konfigurationsform ist für einen Produktionsbetrieb aus Sicherheitsgründen nicht geeignet!

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.

tip

Es gibt einen Guide mit weitergehenden Informationen zu Einsatz und Generierung sicherer Access-Tokens.

Delegation

Mit dem Schlüssel iam/clientId oder der Umgebungsvariable iam__clientId kann die Client-ID festgelegt werden, mit der sich die 5Minds Engine an der Authority anmeldet um einen DelegationToken zu erstellen.

Mit dem Schlüssel iam/clientSecret oder der Umgebungsvariable iam__clientSecret kann das Client-Secret festgelegt werden, mit dem sich die 5Minds Engine an der Authority anmeldet um einen DelegationToken zu erstellen.

Mit dem Schlüssel iam/scope oder der Umgebungsvariable iam__scope kann das Scope festgelegt werden, den die 5Minds Engine verwendet um an der Authority einen DelegationToken zu erstellen.

Beispielkonfiguration

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

{
  "application": {
    "defaultResponseLimit": 1000,
    "name": "5Minds Engine",
    "touchFileOnReady": ""
  },
  "httpServer": {
    "host": "0.0.0.0",
    "port": "10560"
  },
  "httpClient": {
    "allowUnauthorizedCertificates": true
  },
  "tls": {
    "useWindowsTrustStore": true
  },
  "logging": {
    "minLogLevel": "debug"
  },
  "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/",
    "clientId": "atlas_engine",
    "clientSecret": "atlas_engine",
    "scope": "test_resource",
    "allowAnonymousRootAccess": true,
    "rootAccessToken": ""
  }
}

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: ""
  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
  iam__baseUrl: "http://localhost:11560/",
  iam__clientId: "atlas_engine",
  iam__clientSecret: "atlas_engine",
  iam__scope: "test_resource",
  iam__allowAnonymousRootAccess: true,
  iam__rootAccessToken: ""

Wichtig!

Werden zur Konfiguration einer 5Minds Engine sowohl eine JSON-Datei als auch Umgebungsvariablen verwendet, dann haben die Werte in den Umgebungsvariablen Vorrang.

Konfiguration

Referenz​

Datenbank​

Microsoft SQL Server​

PostgreSQL​

SQLite​

Komprimierung​

Connection Pools​

Globales Limit​

Limit pro Engine Prozess​

ID​

Name​

Default Response Limit​

Readyness​

HTTP-Server​

HTTP-Client​

Windows Certificate Trust Store​

Logging​

Authority​

Root Access​

Delegation​

Beispielkonfiguration​

Umgebungsvariablen​