Skip to content

Environment Variables

IntegraMon nutzt mehrere Konfigurationsebenen. Wichtig ist: Nicht jede Einstellung wird auf dieselbe Weise gelesen.

  1. Container-Bootstrap-Werte werden durch deploy/scripts/boot.py aufgebaut
  2. deploy/start.sh sourced die erzeugte .env
  3. Django legt zusaetzliche Fallbacks pro Setting in backend/src/monitorx/settings.py darueber
  4. ein Teil des Laufzeitverhaltens wird danach noch durch DB-basierte Settings wie cMetricSettings, cWorkerTuningSettings und cConfigExt gepraegt

Diese Seite beschreibt das reale Laufzeitverhalten und nicht nur die gewuenschte Theorie.

Effektive Prioritaet

Fuer den Container-Bootstrap gilt:

  1. CONFIG_JSON_B64, falls gesetzt
  2. /run/secrets/app-config.json, falls vorhanden
  3. eine bereits existierende /app/backend/src/.env
  4. hart codierte Fallback-Defaults aus boot.py

Danach sourced start.sh die /app/backend/src/.env in die Shell. Dadurch koennen Keys aus der .env gleichnamige Variablen ueberschreiben, die vorher direkt an den Container uebergeben wurden.

Innerhalb von Django hat danach jedes Setting noch seinen eigenen Fallback. Beispiele:

  • fehlt DB_BACKEND in der .env, faellt Django trotzdem auf sqlite zurueck
  • fehlt CHANNELS_REDIS_URL, faellt Django trotzdem auf redis://127.0.0.1:6379/0 zurueck
  • fehlt DJANGO_ALLOWED_HOSTS, faellt Django trotzdem auf * zurueck

Secret-Decode-Konventionen

core/env_secrets.py unterstuetzt fuer secret-artige Werte wie DB_PASSWORD und EMAIL_HOST_PASSWORD:

  • plain:secret behaelt den Literalwert
  • b64:c2VjcmV0 dekodiert vorher base64
  • <NAME>_B64=true erzwingt base64-Dekodierung fuer <NAME>
  • autodetect dekodiert Werte, die wie base64 aussehen und sauber round-trippen

Das ist relevant fuer:

  • DB_PASSWORD
  • EMAIL_HOST_PASSWORD
  • Mount-Credentials wie SMB_PASS, SSHFS_PASS, KOOFR_APP_PASSWORD

Bootstrap und Dateihandling

Variable Default Pflicht Reales Verhalten
CONFIG_JSON_B64 none nein Base64-kodiertes JSON-Payload. Wenn gesetzt, ist es die primaere Container-Konfigurationsquelle. Ungueltiges base64 oder JSON bricht den Boot ab.
ENV_OUT_PATH /app/backend/src/.env nein Ausgabedatei von boot.py. Hauptsaechlich fuer Custom-Layouts relevant.
ENV_FILE .env relativ zu backend/src nein Optionaler Override fuer Django load_dotenv. Wenn der Pfad nicht laedt, faellt Django auf backend/src/.env zurueck.
APP_VERSION none nein Optionaler PDF-Versionsfallback.
RELEASE_VERSION none nein Optionaler PDF-Versionsfallback.
BUILD_VERSION none nein Optionaler PDF-Versionsfallback.
DOCS_PDF_VERSION Build-Arg oder none nein Bevorzugter Versionsstring fuer PDF-Exports.
DOCS_PDF_LOGO Frontend-Logo-Fallback nein Optionaler Custom-Logo-Pfad fuer PDF-Exports.

Datenbank-Konfiguration

Variable Default Pflicht Reales Verhalten
DB_BACKEND Django-Fallback sqlite; boot.py-Default postgresql praktisch ja fuer berechenbare Docker-Setups Steuert den Branch in settings.py. Unterstuetzte Werte sind sqlite, postgresql, postgres, postgres_neon, postgresql_neon und neon.
DB_ENGINE django.db.backends.sqlite3 oder django.db.backends.postgresql nein Normalerweise kein manueller Override noetig.
DB_NAME db.sqlite3 fuer SQLite-Pfadlogik, default_db_name fuer Postgres-Fallback, monitorx in Sample-JSON SQLite: nein, Postgres: ja Bei SQLite ist es ein Dateiname unter DATA_DIR. Bei Postgres ist es der Datenbankname fuer Django.
DB_USER default_user im Django-Postgres-Fallback, postgres in Sample-JSON Postgres: ja Login-User fuer PostgreSQL.
DB_PASSWORD default_password im Django-Postgres-Fallback, sonst Sample-Werte Postgres: ja Kann plain: oder b64: nutzen.
DB_HOST postgres im Django-Postgres-Fallback, 127.0.0.1 im lokalen Sample-JSON Postgres: ja Hostname des PostgreSQL-Service oder Poolers.
DB_PORT 5432 nein Wird von Django und den Migrationsskripten genutzt.
DB_SSLMODE require fuer Neon-artige Backends nein Wird nur bei den Neon-Varianten angewendet.
DB_CHANNEL_BINDING unset nein Optionaler PostgreSQL-Channel-Binding-Modus.
DJANGO_DB_FILE db.sqlite3 nur SQLite Relativer Dateiname unter DATA_DIR.
SQLITE_TIMEOUT 20 nur SQLite Busy-Timeout in Sekunden fuer SQLite-Schreibzugriffe.
DB_LOCAL wird in start.sh auf true normalisiert nein Steuert nur, ob der interne PostgreSQL-Daemon per Supervisor gestartet wird. Es aendert die Django-Verbindungslogik nicht von allein.
DB_CONNECT_TIMEOUT 2 nein Wird von wait_for_db.py als PGCONNECT_TIMEOUT genutzt.
DB_WAIT_ATTEMPTS 60 nein Retry-Anzahl fuer wait_for_db.py.
DB_WAIT_INTERVAL 2 nein Sleep-Intervall in Sekunden fuer wait_for_db.py.
DB_ALIAS default nein DB-Alias fuer wait_for_db.py.

Redis, Cache, Broker und Channels

Variable Default Pflicht Reales Verhalten
CELERY_BROKER_URL redis://localhost:6379/1 in Django, redis://localhost:6379/0 in boot.py-Defaults ja fuer produktive Worker-Setups Broker-URL fuer Celery. rediss:// aktiviert automatisch CA-basierte TLS-Einstellungen.
CELERY_RESULT_BACKEND redis://localhost:6379/2 in Django, redis://localhost:6379/1 in boot.py-Defaults empfohlen Celery-Result-Storage.
REDIS_CACHE_URL redis://127.0.0.1:6379/0 in Django, redis://localhost:6379/2 in boot.py-Defaults empfohlen Django-Cache plus mehrere Application-Caches.
CHANNELS_REDIS_URL redis://127.0.0.1:6379/0 noetig fuer Websocket-Nutzung Von Django Channels fuer Websocket-Fan-out genutzt.
CELERY_RESULT_EXPIRES 600 nein Result-Expiry in Sekunden.
REDIS_LOCAL wird in start.sh auf true normalisiert nein Steuert nur, ob der interne Redis-Daemon gestartet wird. Ein externer Fallback entsteht dadurch nicht automatisch.

HTTP, Reverse Proxy und URL-Generierung

Variable Default Pflicht Reales Verhalten
PORT 80 in start.sh nein Nginx-Listen-Port fuer das HTTP-Template.
APP_BASE_PATH leer nein Wird auf leer oder /subpath normalisiert. Nutzt Nginx-Rewrites, Frontend-Base-Href-Rewrite und Django-Link-Generierung.
FRONTEND_URL http://localhost:3000 nein Basis-Frontend-URL ohne Subpath.
FRONTEND_BASE_URL leer fuer Mail-Links empfohlen Beste Quelle fuer absolute Links in E-Mails und Templates.
DJANGO_ALLOWED_HOSTS * in Produktion empfohlen Komma-separiertes Django ALLOWED_HOSTS.
ENABLE_SSL false, solange nicht explizit gesetzt nein Beeinflusst nur, welches Nginx-Template gerendert wird. Keine Django-Secure-Mode-Umschaltung.
SERVER_NAME leer nur HTTPS Wird im HTTPS-Nginx-Template als server_name eingesetzt.
SSL_CERT leer nur HTTPS Pfad zur TLS-Zertifikatsdatei.
SSL_KEY leer nur HTTPS Pfad zum TLS-Private-Key.
NGINX_CONF_OVERRIDE leer nein Wenn auf eine existierende Datei zeigend, kopiert start.sh sie direkt und ueberspringt das Template-Rendering.

Storage, Mounts und Logging

Variable Default Pflicht Reales Verhalten
DATA_DIR /app/data im Container, <install_home>/data im lokalen Django-Fallback empfohlen Zentraler Persistenz-Root fuer SQLite, Tenant-Archive, Tenant-Logs und storage-nahe Laufzeitdaten.
LOG_DIR ${DATA_DIR}/logs nein Supervisor-Logs landen hier. Django schreibt hier auch login_activity.log.
LOG_RETENTION_DAYS 3, wenn Archive-Cleanup auf ENV zurueckfaellt nein Wird vom Archive-Cleanup genutzt, wenn kein Tenant-spezifisches jobs.logs die Retention ueberschreibt.
SMB_HOST none optional Aktiviert CIFS-Mount-Versuche ueber mount.py.
SMB_SHARE none optional Share-Name fuer CIFS.
SMB_USER none optional CIFS-User.
SMB_PASS none optional CIFS-Passwort, Secret-Helper werden unterstuetzt.
SMB_MOUNT none optional Lokaler Mount-Pfad.
SMB_VERS 3.1.1 nein SMB-Protokollversion.
SSHFS_HOST none optional Aktiviert SSHFS-Mount-Versuche, wenn SMB nicht gemountet ist.
SSHFS_USER none optional SSHFS-User.
SSHFS_PASS none optional SSHFS-Passwort, wenn kein Key genutzt wird.
SSHFS_KEY none optional SSH-Private-Key fuer SSHFS.
SSHFS_MOUNT none optional Lokaler Mount-Pfad.
KOOFR_EMAIL none optional Koofr-Account fuer rclone.
KOOFR_APP_PASSWORD none optional Koofr-App-Passwort, Secret-Helper werden unterstuetzt.
KOOFR_REMOTE koofr nein rclone-Remote-Name.
KOOFR_SUBPATH leer nein Optionaler Subpath im Koofr-Remote.
KOOFR_MOUNT none optional Lokaler Mount-Pfad fuer rclone mount.

E-Mail und Notification-Delivery

Variable Default Pflicht Reales Verhalten
EMAIL_HOST leer ja fuer SMTP-Delivery SMTP-Host fuer das Django-Mail-Backend.
EMAIL_HOST_USER leer meistens SMTP-Login-User.
EMAIL_HOST_PASSWORD leer meistens SMTP-Passwort, Secret-Helper werden unterstuetzt.
DEFAULT_FROM_EMAIL leer empfohlen Sender-Fallback, wenn Profile nichts ueberschreiben.

Wichtiger Implementierungsdetail:

  • EMAIL_PORT ist aktuell hart auf 587 gesetzt
  • EMAIL_USE_TLS ist aktuell hart auf True gesetzt

Die Basis-.env-Dateien im Repo nennen EMAIL_PORT, aber das aktive Settings-Modul liest es derzeit nicht.

AI- und Integrationsvariablen

Variable Default Pflicht Reales Verhalten
OLLAMA_BASE_URL http://192.168.178.84:11434 nur bei Ollama-Nutzung Default-Ollama-Endpoint in settings.py.
OLLAMA_MODEL llama3 nur bei Ollama-Nutzung Default-Modellname.
OLLAMA_API_URL none optional Wird ausserhalb von settings.py referenziert.
GROQ_API_KEY none optional Von Groq-bezogenen Codepfaden genutzt.
AGENT_DISPATCH_BATCH_SIZE 50 nein Maximale Report-Dispatches pro Periodic-Durchlauf.
CPI_HOST none meist tenant-getrieben Im Code vorhanden, aber aktuelle CPI-Connection-Daten liegen ueberwiegend in cConfigExt.
CPI_USER none meist tenant-getrieben Gleicher Hinweis wie oben.
CPI_PASS none meist tenant-getrieben Gleicher Hinweis wie oben.
FERNET_KEY boot.py hat einen Default, Produktion sollte ueberschreiben praktisch ja Wird zur Verschluesselung von Tenant-Connection-Passwoertern in core/services/config_ext.py genutzt.

Worker-Concurrency-Overrides

Diese Variablen werden vom Supervisor und nicht direkt von Django gelesen:

  • CELERY_LIGHT_CONCURRENCY Default 2
  • CELERY_LIGHT_COLD_CONCURRENCY Default 2
  • CELERY_API_DETAILS_CONCURRENCY Default 3
  • CELERY_API_DETAILS_COLD_CONCURRENCY Default 2
  • CELERY_ALERT_DETAILS_CONCURRENCY Default 1
  • CELERY_ALERTS_CONCURRENCY Default 1
  • CELERY_PERIODIC_CONCURRENCY Default 1
  • CELERY_AI_CONCURRENCY Default 1
  • CELERY_PROCESS_BATCH_CONCURRENCY Default 2
  • CELERY_PROCESS_BATCH_COLD_CONCURRENCY Default 2
  • CELERY_MEDIUM_CONCURRENCY Default 2

Diese Werte werden auch durch das Worker-Tuning im Superadmin gespiegelt.

Variablen, die oft erwartet werden, aber heute nicht verdrahtet sind

  • DEBUG wird nicht aus der Umgebung gelesen. settings.py hat aktuell DEBUG = True.
  • SECRET_KEY wird nicht aus der Umgebung gelesen. Der Django-Secret-Key ist im Source hart codiert.
  • JWT-Signing nutzt damit standardmaessig denselben hart codierten Secret-Key, solange kein Custom-Signing ergaenzt wird.
  • ALLOWED_HOSTS ist nicht der aktive ENV-Key. Aktiv ist DJANGO_ALLOWED_HOSTS.
  • EMAIL_PORT und EMAIL_USE_TLS sind im aktiven Settings-Modul nicht ENV-gesteuert.

Produktions-Empfehlungen

  • DJANGO_ALLOWED_HOSTS explizit setzen und nicht * in Produktion belassen.
  • FERNET_KEY durch ein stabiles extern verwaltetes Secret ersetzen.
  • PostgreSQL fuer geteilte oder schreibintensive Umgebungen nutzen.
  • Explizite externe Redis-URLs setzen, wenn REDIS_LOCAL=false.
  • FRONTEND_BASE_URL setzen, sobald das System Links per E-Mail verschickt.
  • NGINX_CONF_OVERRIDE nur bewusst nutzen, weil damit die Standard-Templates umgangen werden.
  • CONFIG_JSON_B64 und /run/secrets/app-config.json als unterstuetzte Docker-Bootstrap-Eingaenge behandeln.