Konfigurationsreferenz¶

TCM365 wird über Umgebungsvariablen konfiguriert, die in der Datei backend-js/.env definiert werden. Diese Referenz dokumentiert jede verfügbare Variable, ihren Zweck, Standardwert und ob sie erforderlich ist.

Schneller Einstieg

Kopieren Sie backend-js/.env.example nach backend-js/.env und bearbeiten Sie die Werte. Das automatisierte Setup-Skript (scripts/setup.sh oder scripts/setup.ps1) erstellt diese Datei für Sie.

Anwendungseinstellungen¶

Grundlegende Anwendungskonfiguration, die Serververhalten, Authentifizierungs-Tokens und Debug-Modus steuert.

Variable	Erforderlich	Standard	Beschreibung
`PORT`	Nein	`8000`	HTTP-Port, auf dem der Backend-Server lauscht
`APP_SECRET_KEY`	Ja	--	JWT-Signatur-Secret. Mindestens 32 Zeichen. Generieren mit `openssl rand -hex 32`.
`APP_DEBUG`	Nein	`false`	Debug-Modus mit ausfuehrlichem Logging aktivieren. Nur in der Entwicklung auf `true` setzen.
`APP_ACCESS_TOKEN_EXPIRE_MINUTES`	Nein	`30`	JWT Access Token-Lebensdauer in Minuten
`NODE_ENV`	Nein	`development`	Laufzeitumgebung: `development`, `production` oder `test`

APP_SECRET_KEY Sicherheit

Der APP_SECRET_KEY wird zum Signieren von JWT-Tokens verwendet. Verwenden Sie in der Produktion einen kryptographisch zufaelligen String von mindestens 32 Zeichen. Verwenden Sie niemals den Beispielwert wieder und committen Sie dieses Secret nicht in die Versionskontrolle.

Beispiel:

PORT=8000
APP_SECRET_KEY="a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"
APP_DEBUG=false
APP_ACCESS_TOKEN_EXPIRE_MINUTES=30
NODE_ENV=development

Datenbankeinstellungen¶

PostgreSQL-Verbindungsparameter. TCM365 verwendet TypeORM mit zwei Datenbankrollen für die Sicherheit: tcm_admin (umgeht RLS für Migrationen) und tcm_app (respektiert RLS für Anwendungsabfragen).

Variable	Erforderlich	Standard	Beschreibung
`DATABASE_HOST`	Ja	`localhost`	PostgreSQL-Server-Hostname
`DATABASE_PORT`	Nein	`5432`	PostgreSQL-Server-Port
`DATABASE_USERNAME`	Ja	--	Datenbank-Benutzername (sollte die Admin-Rolle für Migrationen sein)
`DATABASE_PASSWORD`	Ja	--	Datenbank-Passwort
`DATABASE_NAME`	Ja	`tcm_db`	Datenbankname
`DATABASE_LOGGING`	Nein	`false`	SQL-Query-Logging aktivieren. Nuetzlich für Debugging.
`DATABASE_SSL`	Nein	`false`	SSL für Datenbankverbindungen aktivieren (empfohlen für Produktion)
`DATABASE_CA_CERT`	Nein	--	Pfad zum CA-Zertifikat für SSL-Verbindungen

Row-Level Security (RLS)

TCM365 implementiert eine Drei-Schichten Tenant-Isolation. Der Anwendungsbenutzer (tcm_app) unterliegt RLS-Policies, die den Datenzugriff auf den Bereich der aktuellen Organisation beschränken. Der Admin-Benutzer (tcm_admin) umgeht RLS für administrative Operationen.

Beispiel:

DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_USERNAME=tcm_admin
DATABASE_PASSWORD=sicheres_passwort_hier
DATABASE_NAME=tcm_db
DATABASE_LOGGING=false

Azure Active Directory¶

Azure AD-Konfiguration für die Microsoft 365-Integration. Diese Einstellungen werden für den OAuth 2.0 Client Credentials Flow zum Zugriff auf die Microsoft Graph API und UTCM API verwendet.

Variable	Erforderlich	Standard	Beschreibung
`AZURE_AD_TENANT_ID`	Bedingt	--	Azure AD Directory (Tenant) ID. Erforderlich für M365-Features.
`AZURE_AD_CLIENT_ID`	Bedingt	--	Azure AD App Registration Client (Application) ID
`AZURE_AD_CLIENT_SECRET`	Bedingt	--	Azure AD App Registration Client Secret
`AZURE_AD_AUTHORITY`	Nein	`https://login.microsoftonline.com/{tenant-id}`	Azure AD Authority URL
`AZURE_AD_REDIRECT_URI`	Nein	`http://localhost:8000/api/v1/auth/callback`	OAuth Redirect URI
`AZURE_AD_SCOPES`	Nein	`https://graph.microsoft.com/.default`	OAuth Scopes für Graph API-Zugriff

Bedingte Anforderung

Azure AD-Variablen sind nur erforderlich, wenn Sie Microsoft 365-Features nutzen möchten. TCM365 funktioniert vollständig für Zscaler und lokale Features ohne diese Einstellungen.

Erforderliche Microsoft Graph API-Berechtigungen:

Berechtigung	Typ	Zweck
`Directory.Read.All`	Application	Entra ID-Konfigurationen lesen
`Policy.Read.All`	Application	Conditional Access Policies lesen
`DeviceManagementConfiguration.Read.All`	Application	Intune-Konfigurationen lesen
`SecurityEvents.Read.All`	Application	Defender-Konfigurationen lesen
`AuditLog.Read.All`	Application	Audit Logs für Change Attribution lesen
`UnifiedTenantConfigurationManagement.Read.All`	Application	UTCM Snapshot Job API-Zugriff

Beispiel:

AZURE_AD_TENANT_ID="12345678-abcd-efgh-ijkl-123456789012"
AZURE_AD_CLIENT_ID="87654321-dcba-hgfe-lkji-210987654321"
AZURE_AD_CLIENT_SECRET="ihr-client-secret-wert"
AZURE_AD_AUTHORITY="https://login.microsoftonline.com/12345678-abcd-efgh-ijkl-123456789012"
AZURE_AD_REDIRECT_URI="http://localhost:8000/api/v1/auth/callback"
AZURE_AD_SCOPES="https://graph.microsoft.com/.default"

Storage Backend¶

TCM365 unterstützt zwei Storage Backends für Snapshots, Reports und andere Dateiartefakte.

Variable	Erforderlich	Standard	Beschreibung
`STORAGE_BACKEND`	Nein	`local`	Storage-Provider: `local` oder `azure`
`LOCAL_STORAGE_PATH`	Bedingt	`./data`	Lokaler Dateisystempfad für Dateispeicherung. Erforderlich bei `STORAGE_BACKEND=local`.
`AZURE_STORAGE_CONNECTION_STRING`	Bedingt	--	Azure Blob Storage Connection String. Erforderlich bei `STORAGE_BACKEND=azure`.
`AZURE_STORAGE_CONTAINER`	Bedingt	`tcm-data`	Azure Blob Storage Container-Name

Lokaler Storage¶

Für Entwicklung und Tests verwenden Sie lokalen Dateisystem-Storage:

STORAGE_BACKEND=local
LOCAL_STORAGE_PATH=./data

TCM365 erstellt die erforderliche Verzeichnisstruktur automatisch. Der Diagnostics-Endpoint kann fehlende Verzeichnisse reparieren über POST /api/v1/diagnostics/repair?action=create_storage_dirs.

Azure Blob Storage¶

Für Produktionsbereitstellungen verwenden Sie Azure Blob Storage:

STORAGE_BACKEND=azure
AZURE_STORAGE_CONNECTION_STRING="DefaultEndpointsProtocol=https;AccountName=..."
AZURE_STORAGE_CONTAINER=tcm-data

Redis¶

Redis wird für Rate Limiting, Distributed Locks (Capture Lock Service) und Token Blacklisting verwendet. Es ist optional -- TCM365 fällt auf In-Memory-Alternativen zurück, wenn Redis nicht verfügbar ist.

Variable	Erforderlich	Standard	Beschreibung
`REDIS_URL`	Nein	--	Redis Connection URL (z.B. `redis://localhost:6379/0`)
`REDIS_PASSWORD`	Nein	--	Redis-Passwort (falls Authentifizierung aktiviert)
`REDIS_TLS`	Nein	`false`	TLS für Redis-Verbindungen aktivieren

In-Memory Fallback

Wenn Redis nicht konfiguriert oder nicht verfügbar ist:

Rate Limiting fällt auf ein In-Memory Sliding Window zurück
Capture Locks fallen auf einen In-Memory Mutex pro Tenant zurück
Token Blacklist fällt auf ein In-Memory Set zurück

Dies ist ausreichend für Single-Instance-Bereitstellungen und Entwicklung. Für Multi-Instance-Produktionsbereitstellungen wird Redis für ordnungsgemaesse verteilte Koordination empfohlen.

Beispiel:

REDIS_URL="redis://localhost:6379/0"

KI-Analyse (OpenAI)¶

Optionale Integration mit OpenAI oder Azure OpenAI für KI-gestützte Konfigurationsanalyse, Best-Practice-Empfehlungen und Blueprint-Bewertung.

Variable	Erforderlich	Standard	Beschreibung
`OPENAI_API_KEY`	Nein	--	OpenAI API Key (beginnt mit `sk-`)
`OPENAI_MODEL`	Nein	`gpt-4`	OpenAI-Modell für die Analyse
`OPENAI_BASE_URL`	Nein	--	Benutzerdefinierte API-Basis-URL (für Azure OpenAI verwenden)
`OPENAI_API_VERSION`	Nein	--	API-Version (erforderlich für Azure OpenAI, z.B. `2024-02-15-preview`)

Standard OpenAIAzure OpenAI

OPENAI_API_KEY="sk-ihr-api-key"
OPENAI_MODEL="gpt-4"

OPENAI_API_KEY="ihr-azure-openai-key"
OPENAI_MODEL="gpt-4"
OPENAI_BASE_URL="https://ihre-resource.openai.azure.com"
OPENAI_API_VERSION="2024-02-15-preview"

KI-Features sind optional

Wenn kein OpenAI API Key konfiguriert ist, werden KI-Analyse-Features einfach in der UI deaktiviert. Der Rest der Plattform funktioniert normal.

E-Mail-Benachrichtigungen (SMTP)¶

SMTP-Konfiguration für den Versand von E-Mail-Benachrichtigungen (Drift Alerts, Reports, Incident-Updates).

Variable	Erforderlich	Standard	Beschreibung
`SMTP_HOST`	Nein	--	SMTP-Server-Hostname
`SMTP_PORT`	Nein	`587`	SMTP-Server-Port
`SMTP_USERNAME`	Nein	--	SMTP-Authentifizierungs-Benutzername
`SMTP_PASSWORD`	Nein	--	SMTP-Authentifizierungs-Passwort
`SMTP_FROM_EMAIL`	Nein	--	Absender-E-Mail-Adresse
`SMTP_FROM_NAME`	Nein	`TCM Notifications`	Absender-Anzeigename
`SMTP_SECURE`	Nein	`false`	TLS für SMTP-Verbindung verwenden

Beispiel:

SMTP_HOST="smtp.office365.com"
SMTP_PORT=587
SMTP_USERNAME="notifications@contoso.com"
SMTP_PASSWORD="smtp-passwort"
SMTP_FROM_EMAIL="tcm@contoso.com"
SMTP_FROM_NAME="TCM365 Notifications"

CORS¶

Cross-Origin Resource Sharing-Konfiguration. Steuert, welche Frontend-Origins auf die Backend-API zugreifen können.

Variable	Erforderlich	Standard	Beschreibung
`CORS_ORIGINS`	Nein	`http://localhost:3000,http://localhost:5173,http://localhost:8080`	Kommagetrennte Liste erlaubter Origins

Beispiel:

# Entwicklung (mehrere lokale Ports)
CORS_ORIGINS="http://localhost:3000,http://localhost:5173,http://localhost:8080"

# Produktion (Ihre Domain)
CORS_ORIGINS="https://tcm365.contoso.com"

CORS in der Produktion

Beschraenken Sie CORS in der Produktion auf Ihre tatsächliche Frontend-Domain. Verwenden Sie niemals Wildcard-Origins (*) in der Produktion.

Per-Tenant-Verschlüsselung¶

TCM365 verschlüsselt Tenant-Credentials (Azure AD Client Secrets, Zscaler API Keys) im Ruhezustand über ein erweiterbares SecretBackend-Interface.

Variable	Erforderlich	Standard	Beschreibung
`ENCRYPTION_BACKEND`	Nein	`local`	Verschluesselungs-Backend: `local` (AES-256) oder `azure` (Key Vault)
`ENCRYPTION_KEY`	Bedingt	Abgeleitet von `APP_SECRET_KEY`	AES-256-Verschluesselungsschluessel für lokales Backend
`AZURE_KEY_VAULT_URL`	Bedingt	--	Azure Key Vault URL für Produktionsverschluesselung

Local AES (Entwicklung)Azure Key Vault (Produktion)

ENCRYPTION_BACKEND=local
# Verwendet standardmaessig einen von APP_SECRET_KEY abgeleiteten Schlüssel

ENCRYPTION_BACKEND=azure
AZURE_KEY_VAULT_URL="https://ihr-keyvault.vault.azure.net"

Vollstaendiges .env-Beispiel¶

Eine minimale funktionierende Konfiguration für lokale Entwicklung:

# Anwendung
PORT=8000
APP_SECRET_KEY="ändern-sie-dies-zu-einem-32-zeichen-minimum-zufallsstring"
APP_DEBUG=false
APP_ACCESS_TOKEN_EXPIRE_MINUTES=30

# Datenbank (PostgreSQL)
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_USERNAME=tcm_admin
DATABASE_PASSWORD=tcm_passwort
DATABASE_NAME=tcm_db
DATABASE_LOGGING=false

# Storage (lokal für Entwicklung)
STORAGE_BACKEND=local
LOCAL_STORAGE_PATH=./data

# CORS
CORS_ORIGINS="http://localhost:3000,http://localhost:5173,http://localhost:8080"

# --- Optional ab hier ---

# Redis (fällt auf In-Memory zurück, wenn nicht gesetzt)
# REDIS_URL="redis://localhost:6379/0"

# Azure AD (erforderlich für M365-Features)
# AZURE_AD_TENANT_ID=""
# AZURE_AD_CLIENT_ID=""
# AZURE_AD_CLIENT_SECRET=""

# KI-Analyse (optional)
# OPENAI_API_KEY="sk-..."
# OPENAI_MODEL="gpt-4"

# SMTP (optional, für E-Mail-Benachrichtigungen)
# SMTP_HOST="smtp.example.com"
# SMTP_PORT=587
# SMTP_USERNAME=""
# SMTP_PASSWORD=""
# SMTP_FROM_EMAIL="tcm@example.com"
# SMTP_FROM_NAME="TCM Notifications"

Umgebungsvalidierung¶

TCM365 validiert Umgebungsvariablen beim Start über Joi-Schemas, die in backend-js/src/config/validation.schema.ts definiert sind. Wenn erforderliche Variablen fehlen oder ungültig sind, startet die Anwendung nicht und gibt eine beschreibende Fehlermeldung aus.

Häufige Validierungsfehler:

Fehler	Ursache	Behebung
`APP_SECRET_KEY must be at least 32 characters`	Secret Key zu kurz	Laengeren Key generieren: `openssl rand -hex 32`
`DATABASE_HOST is required`	Fehlende Datenbankkonfiguration	`DATABASE_HOST` in `.env` setzen
`STORAGE_BACKEND must be one of [local, azure]`	Ungueltiger Storage-Wert	`local` oder `azure` verwenden