Zum Hauptinhalt springen

Container-Deployment

Die IDIAL-APP wird als Docker-Container ausgeliefert. Vor dem ersten Start müssen ein Verschlüsselungsschlüssel erzeugt und persistente Volumes eingerichtet werden. Der Container validiert bei jedem Start automatisch seine Konfiguration — schlägt eine Prüfung fehl, bricht er mit einem definierten Exit-Code ab, bevor die Anwendung startet.

Voraussetzungen​

  • Docker Engine ≥ 20.10 oder Docker Compose ≥ 2.x
  • Zugriff auf das BxC-Container-Registry

Master Key erzeugen​

Der Master Key ist der einzige externe Schlüssel, den die IDIAL-APP benötigt. Er ver- und entschlüsselt alle in der Anwendung gespeicherten Credentials (IDIAL-API-Keys, OIDC-Secrets usw.). Der Schlüssel muss base64-kodiert sein und dekodiert exakt 32 Bytes (256 Bit) ergeben.

gefahr

Diesen Schlüssel sicher verwahren. Ein verlorener Master Key bedeutet, dass alle gespeicherten Credentials unwiederbringlich verloren sind. Der Schlüssel muss bei jedem Neustart des Containers identisch übergeben werden — ein geänderter Schlüssel bricht den Start mit Exit-Code 21 ab.

Der Schlüssel wird der IDIAL-APP über eine Umgebungsvariable oder eine Schlüsseldatei übergeben. In Produktivumgebungen ist die Umgebungsvariable IDIAL_MASTER_KEY zu bevorzugen: Der Schlüssel kann so zur Laufzeit aus einem HSM oder KMS (z. B. PKCS#11, AWS KMS, HashiCorp Vault) in die Variable geladen werden und liegt dabei niemals unverschlüsselt auf dem Dateisystem. Für Lab- und Testumgebungen eignet sich die Datei-Variante (IDIAL_MASTER_KEY_FILE).

Lab-Setup — Schlüssel schnell erzeugen
openssl rand -base64 32

In Produktivumgebungen muss sichergestellt sein, dass der Schlüssel mit ausreichend Entropie erzeugt, sicher gespeichert und separat gesichert wird.

Deployment mit Docker Compose (empfohlen)​

Verzeichnisstruktur anlegen​

mkdir -p idial-app/{secrets,data,config,logs}
cd idial-app

Master Key sichern (Lab-Setup)​

openssl rand -base64 32 > secrets/master_key.txt
chmod 600 secrets/master_key.txt

docker-compose.yml​

services:
  idial-app:
    image: registry.bxc-security.com/idial-app:latest
    container_name: idial-app
    restart: unless-stopped

    environment:
      - IDIAL_MASTER_KEY_FILE=/run/secrets/master_key
      - PORT=5555
      - LOG_LEVEL=INFO

    secrets:
      - source: master_key
        target: /run/secrets/master_key
        mode: 0400

    volumes:
      - ./data:/app/runtime_data
      - ./config:/app/config
      - ./logs:/app/logs

    ports:
      - "443:5555"

    healthcheck:
      test: ["CMD", "curl", "-fsk", "https://localhost:5555/api/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 30s

secrets:
  master_key:
    file: secrets/master_key.txt

Container starten​

docker compose up -d

Erststart vs. Neustart​

Erststart​

Beim ersten Start legt der Container folgende Dateien und Strukturen automatisch an:

Pfad im ContainerInhaltAktion
/app/runtime_data/containers.jsonLeere Container-ListeWird neu erstellt
/app/runtime_data/users.jsonWird beim ersten Login angelegt—
/app/config/crypto/encrypted_keystore.jsonVerschlüsselter Test-Datensatz zur SchlüsselvalidierungWird neu erstellt
/app/runtime_data/certs/cert.pem + key.pemSelbstsigniertes TLS-Zertifikat (4096-Bit RSA)Wird automatisch generiert

Der Erststart dauert typischerweise 8–10 Sekunden (inkl. TLS-Zertifikat-Generierung).

Neustart​

Bei einem Neustart durchläuft der Container dieselbe Validierungskette, ist aber deutlich schneller (~2–3 Sekunden), da Verzeichnisse, Keystore und TLS-Zertifikat bereits vorhanden sind.

warnung

Derselbe Master Key ist Pflicht. Wird beim Neustart ein anderer Schlüssel übergeben, schlägt die Keystore-Validierung fehl (Exit-Code 23) und der Container startet nicht.

Startup-Validierungskette​

Der Entrypoint-Skript validiert bei jedem Start in dieser Reihenfolge:

  1. Crypto-Konfiguration — Master Key vorhanden, Base64-Format korrekt, 32-Byte-Länge exakt, bestehender Keystore entschlüsselbar
  2. Verzeichnisse & Schreibrechte — Volumes gemountet und beschreibbar
  3. Port-Verfügbarkeit — Konfigurierter Port nicht belegt
  4. Crypto-Health-Check — Verschlüsselung und Entschlüsselung funktionieren
  5. TLS-Setup — Eigene Zertifikate laden oder selbstsignierte generieren
  6. Appstart — Gunicorn mit 4 Worker-Prozessen

Scheitert ein Schritt, beendet sich der Container mit einem definierten Exit-Code (siehe Konfigurationsreferenz).

Eigene TLS-Zertifikate verwenden​

Standardmäßig generiert der Container beim Erststart ein selbstsigniertes Zertifikat. Um ein eigenes Zertifikat zu verwenden, die Dateien vor dem Start in das Volume legen:

cp /pfad/zu/cert.pem data/certs/cert.pem
cp /pfad/zu/key.pem  data/certs/key.pem

Der Container erkennt vorhandene Zertifikate automatisch und überspringt die Generierung.

Gesundheit prüfen​

# Basis-Health-Check (ohne Authentifizierung)
curl -sk https://localhost/api/health
# Antwort: {"status": "healthy", "service": "IDIAL Management API"}

# Crypto-System-Status (Admin-Authentifizierung erforderlich)
curl -sk https://localhost/api/health/crypto

Logs prüfen​

# Live-Log des Containers
docker compose logs -f idial-app

# Nur Startup-Ausgabe (letzte 50 Zeilen)
docker compose logs --tail=50 idial-app

Erwartete Ausgabe bei erfolgreichem Start:

[OK] Master key provided via environment variable
[OK] Master key format validated (32 bytes)
[OK] Crypto system test passed
[OK] Write permissions verified
[OK] SSL certificates found
[OK] All validations passed - starting application
Starting IDIAL Web Backend with Gunicorn...
[INFO] Starting HTTPS server on port 5555