Deklarative Systemkonfiguration

Wofür ist es gedacht?

Die Backend-API von docuteam Context bietet Funktionen, um Archive und deren zugehörige Konfigurationen deklarativ mit versionierten YAML-Dateien zu verwalten.

Typische Anwendungsfälle sind:

• Konfigurationsänderungen vor der Anwendung vorzubereiten und zu prüfen,
• eine gut lesbare Historie von Konfigurationsänderungen zu führen,
• dieselbe Konfiguration in einer anderen Umgebung wiederzuverwenden,
• einen bekannten Konfigurationsstand wiederherzustellen.

Was kann konfiguriert werden?

Die Konfiguration umfasst derzeit diese archivbezogenen Einstellungen:

• Einstellungen für die Attachment-Verbindung,
• App-Konfiguration,
• Box-Verbindungen.

Aufbau der Konfiguration

Das folgende Beispiel zeigt eine Konfiguration mit allen derzeit verfügbaren Eigenschaften:

version: 1
archives:
  - name: myArchive
    attachment:
      connection:
        region: context
        endpoint: http://localhost:9000
        accessKey: admin
        secretKey: ENV(archive_myArchive_attachmentConnection_secretKey)
        bucketName: context-s3-mock
        downloadUrlMaxAgeInSeconds: 60
        maxFileSizeInBytes: 5368709120
        allowedMimeTypes:
          - application/pdf
          - image/jpeg
    appConfig:
      appTitle: Development server
      header:
        icon: <encoded_image>
        backgroundColor: "#FFFFFF"
        textColor: "#000000"
      menu:
        backgroundColor: "#FFFFFF"
        textColor: "#000000"
        textColorHover: "#222222"
    boxConnections:
      - name: public-box
        url: https://example.com/box
        namespace:
          - public
        token: ENV(archive_myArchive_boxConnection_public-box_token)

version bezeichnet die aktuell implementierte Version.

archives ist eine Liste der vorhandenen Archive. Die Eigenschaft name bezeichnet dabei den eindeutigen Bezeichner eines Archivs. Wenn überhaupt kein Konfigurationszustand vorhanden sein soll, kann der Wert von archives leer bleiben. Die minimal gültige Konfiguration lautet daher:

version: 1
archives:

connection definiert einen Verbindungspunkt für Attachments. Er kann leer bleiben, wenn keine Verbindung enthalten sein soll. Wenn eine Verbindung konfiguriert wird, müssen jedoch alle folgenden Eigenschaften vorhanden sein: region, endpoint, accessKey, secretKey, bucketName, downloadUrlMaxAgeInSeconds, maxFileSizeInBytes, allowedMimeTypes.

appConfig konfiguriert das Erscheinungsbild der Anwendung. Alle Eigenschaften sind optional. Der Block kann also entweder vollständig leer bleiben oder nur die gewünschten Eigenschaften enthalten.

boxConnections ist eine Liste von Box-Verbindungen. Sie kann leer bleiben, wenn keine Verbindungen enthalten sein sollen. Wird eine Verbindung definiert, muss sie alle folgenden Eigenschaften enthalten: name, url, namespace und token.

Die minimale Konfiguration für ein einzelnes Archiv lautet daher:

version: 1
archives:
  - name: myArchive
    attachment:
      connection:
    appConfig:
    boxConnections:

Umgebungsvariablen

Geheime Werte können mit ENV(env_variable_key) auf Umgebungsvariablen verweisen.

Für die Schlüssel der Attachment-Verbindung und der Box-Verbindungen ist folgende Benennung vorgesehen:

ENV(archive_$archiveName_attachmentConnection_secretKey) ENV(archive_$archiveName_boxConnection_$boxName_token)

Diese Konvention wird beim Abrufen des aktuellen Konfigurationszustands verwendet.

Aktuellen Konfigurationszustand abrufen

Verwende den Endpunkt GET /api/system-config/get, um den aktuellen Systemkonfigurationszustand als YAML zu exportieren.

Der Response-Content-Type ist application/yaml.

Der Endpunkt liefert die Konfiguration als serialisierten YAML-Text zurück, also als YAML-String und nicht als JSON-Objekt.

Der Endpunkt erfordert aktuell eine Authentifizierung per Bearer-Token.

Flags

Der Endpunkt unterstützt das folgende optionale Query-Flag:

• includeInfo=true
  Fügt am Anfang des exportierten YAML einen info-Block hinzu. Dieser Block enthält Metadaten zum Export:
  • date: den Zeitstempel des Exports im ISO-Format,
  • user: den Benutzernamen des authentifizierten Benutzers, falls verfügbar.

Wird das Flag nicht gesetzt oder auf einen anderen Wert als true gesetzt, wird der info-Block nicht ausgegeben.

Beispiele

Aktuelle Konfiguration ohne Metadaten abrufen:

curl \
  -H "Accept: application/yaml" \
  -H "Authorization: Bearer <access-token>" \
  "http://localhost:3333/api/system-config/get"

Aktuelle Konfiguration inklusive Export-Metadaten abrufen:

curl \
  -H "Accept: application/yaml" \
  -H "Authorization: Bearer <access-token>" \
  "http://localhost:3333/api/system-config/get?includeInfo=true"

Beispielantwort mit includeInfo=true:

info:
  date: 2026-06-10T12:00:00.000Z
  user: alice
version: 1
archives:
  - name: myArchive
    attachment:
      connection:
    appConfig:
    boxConnections:

Das exportierte YAML kann geprüft, versioniert und später erneut an den Apply-Endpunkt gesendet werden. Falls ein info-Block vorhanden ist, wird er beim Import ignoriert.

Konfiguration anwenden

Verwende den Endpunkt POST /api/system-config/apply, um eine YAML-Konfiguration zu validieren und anzuwenden.

Sende das YAML-Dokument selbst als rohen Request-Body mit dem Content-Type application/yaml.

Der Request-Body wird zunächst als reiner Text eingelesen und anschließend als YAML interpretiert. Mit anderen Worten: Der Endpunkt erwartet einen YAML-String im Body und keinen JSON-Wrapper.

Der Endpunkt ist in der aktuellen Implementierung öffentlich erreichbar und erfordert derzeit keinen Authorization-Header.

Flags

Der Endpunkt unterstützt das folgende optionale Query-Flag:

• dryRun=true
  Validiert das YAML, löst Verweise auf Umgebungsvariablen auf, vergleicht den gewünschten Zustand mit dem aktuellen Zustand und gibt die geplanten Änderungen zurück, wendet diese aber nicht an.

Wird das Flag nicht gesetzt oder auf einen anderen Wert als true gesetzt, wird die Konfiguration tatsächlich angewendet.

Beispiele

Konfiguration validieren, ohne sie anzuwenden:

curl \
  -X POST \
  -H "Content-Type: application/yaml" \
  --data-binary @system-config.yaml \
  "http://localhost:3333/api/system-config/apply?dryRun=true"

Konfiguration anwenden:

curl \
  -X POST \
  -H "Content-Type: application/yaml" \
  --data-binary @system-config.yaml \
  "http://localhost:3333/api/system-config/apply"

Antwort

Der Endpunkt liefert einen Plain-Text-Statusbericht zurück, der das Ergebnis der Validierung und des Apply-Vorgangs beschreibt.

Typische Antworten sind:

• No changes
  Die übermittelte Konfiguration entspricht bereits dem aktuellen Systemzustand.

• Eine Liste geplanter oder ausgeführter Änderungen, zum Beispiel:

  update Archive myArchive
  - attachment.connection.endpoint: http://old.example -> http://new.example

• Wenn Änderungen erfolgreich angewendet wurden, endet die Antwort mit:

  Changes applied successfully.

Validierung und Umgebungsvariablen

Beim Import wird das YAML strikt geparst und validiert:

• ungültige YAML-Syntax,
• fehlende Pflichtfelder,
• unbekannte Eigenschaften,
• doppelte Archivnamen oder doppelte Namen von Box-Verbindungen innerhalb desselben Archivs

führen zu einem 400 Bad Request.

Verweise auf Umgebungsvariablen in der Form ENV(MY_KEY) werden beim Import aufgelöst. Falls eine referenzierte Umgebungsvariable fehlt, schlägt der Request fehl.

Eine exportierte Datei mit einem info-Block kann unverändert an den Apply-Endpunkt zurückgesendet werden, da der info-Block beim Import ignoriert wird.