Umgebungsvariablen¶

Alle Konfigurationsparameter des Kamerplanter-Backends werden über Umgebungsvariablen gesteuert. Die Variablen werden von pydantic-settings geladen — Groß-/Kleinschreibung ist nicht relevant.

Lokale Konfiguration

Für die Docker-Compose-Umgebung alle Werte in eine .env-Datei im Repository-Wurzelverzeichnis eintragen. Eine Vorlage liegt als .env.example bereit:

cp .env.example .env

Datenbankverbindung¶

Variable	Standard	Pflicht	Beschreibung
`ARANGODB_HOST`	`localhost`	Ja	Hostname oder IP-Adresse der ArangoDB-Instanz
`ARANGODB_PORT`	`8529`	Nein	TCP-Port der ArangoDB
`ARANGODB_DATABASE`	`kamerplanter`	Ja	Name der Zieldatenbank
`ARANGODB_USERNAME`	`root`	Ja	Datenbanknutzer
`ARANGODB_PASSWORD`	—	Ja	Passwort des Datenbanknutzers
`ARANGO_ROOT_PASSWORD`	—	Ja*	Root-Passwort für den ArangoDB-Container (nur Docker)

*ARANGO_ROOT_PASSWORD wird direkt an den ArangoDB-Container übergeben und ist für den Start der Datenbank erforderlich.

Produktionspasswörter

Verwenden Sie niemals den Standardwert rootpassword in produktiven Umgebungen. Generieren Sie sichere Passwörter: openssl rand -hex 32

Cache und Aufgaben-Queue¶

Variable	Standard	Pflicht	Beschreibung
`REDIS_URL`	`redis://localhost:6379/0`	Ja	Verbindungs-URL für Redis oder Valkey (Celery Broker und Backend-Cache)

Format: redis://[user]:[password]@[host]:[port]/[db]

Beispiele:

redis://localhost:6379/0                    # Lokal ohne Auth
redis://:meinpasswort@redis:6379/0          # Mit Passwort
rediss://user:pass@redis-host:6380/1        # TLS (rediss://)

Sicherheit und Authentifizierung¶

Variable	Standard	Pflicht	Beschreibung
`JWT_SECRET_KEY`	`change-me-in-production-...`	Ja	Geheimer Schlüssel für JWT-Signierung (HS256)
`JWT_ALGORITHM`	`HS256`	Nein	JWT-Signaturalgorithmus
`ACCESS_TOKEN_EXPIRE_MINUTES`	`15`	Nein	Gültigkeitsdauer des JWT-Access-Tokens in Minuten
`REFRESH_TOKEN_EXPIRE_DAYS`	`30`	Nein	Gültigkeitsdauer des Refresh-Tokens in Tagen
`FERNET_KEY`	—	Nein	Fernet-Schlüssel zum Verschlüsseln von OIDC-Provider-Secrets
`REQUIRE_EMAIL_VERIFICATION`	`false`	Nein	E-Mail-Verifikation bei Registrierung erzwingen
`HIBP_ENABLED`	`false`	Nein	"Have I Been Pwned"-Prüfung bei Passwortänderung aktivieren

JWT_SECRET_KEY in Produktion ändern

Der Standardwert change-me-in-production-use-openssl-rand-hex-32 darf in produktiven Umgebungen nicht verwendet werden. Generieren Sie einen sicheren Wert:

openssl rand -hex 32

Änderungen des JWT_SECRET_KEY machen alle aktiven Tokens ungültig — alle Nutzer werden abgemeldet.

Betriebsmodus¶

Variable	Standard	Pflicht	Beschreibung
`KAMERPLANTER_MODE`	`full`	Nein	Betriebsmodus: `full` (Auth + Mandanten) oder `light` (kein Auth, lokale Einzelnutzung)
`DEBUG`	`false`	Nein	Debug-Logging aktivieren (verbose, nie in Produktion)
`FRONTEND_URL`	`http://localhost:5173`	Nein	URL des Frontends (wird für E-Mail-Links verwendet)

Light-Modus (`KAMERPLANTER_MODE=light`)¶

Im Light-Modus entfällt die Token-Authentifizierung. Die API ist ohne Anmeldung verwendbar. Dieser Modus ist für lokale Einzelinstallationen ohne Internet-Exposition gedacht.

Light-Modus nicht öffentlich exponieren

Der Light-Modus deaktiviert alle Authentifizierungsschichten. Niemals mit einem öffentlich erreichbaren Port betreiben.

CORS-Konfiguration¶

Variable	Standard	Pflicht	Beschreibung
`CORS_ORIGINS`	`["http://localhost:3000","http://localhost:5173"]`	Nein	JSON-Array erlaubter Origins für CORS

Format: Immer als JSON-Array im String-Format:

CORS_ORIGINS='["https://app.example.com","https://app2.example.com"]'

E-Mail¶

Variable	Standard	Pflicht	Beschreibung
`EMAIL_ADAPTER`	`console`	Nein	E-Mail-Adapter: `console` (Ausgabe im Log), `smtp`, `resend`
`SMTP_HOST`	`localhost`	Nein	SMTP-Server-Hostname
`SMTP_PORT`	`587`	Nein	SMTP-Port
`SMTP_USERNAME`	—	Nein	SMTP-Benutzername
`SMTP_PASSWORD`	—	Nein	SMTP-Passwort
`SMTP_FROM_EMAIL`	`noreply@kamerplanter.example`	Nein	Absenderadresse für System-E-Mails
`SMTP_USE_TLS`	`true`	Nein	STARTTLS für SMTP aktivieren

Im Entwicklungsmodus (EMAIL_ADAPTER=console) werden E-Mails nicht gesendet, sondern im Backend-Log ausgegeben.

Externe Datenanreicherung (REQ-011)¶

Variable	Standard	Pflicht	Beschreibung
`PERENUAL_API_KEY`	—	Nein	API-Schlüssel für Perenual-Pflanzendatenbank
`TREFLE_API_KEY`	—	Nein	API-Schlüssel für Tréflé-Pflanzendatenbank
`ENRICHMENT_HTTP_TIMEOUT`	`30`	Nein	HTTP-Timeout für externe API-Anfragen (Sekunden)

GBIF wird ohne API-Key verwendet (öffentliche API). Perenual und Tréflé erfordern kostenlose Registrierung.

Home Assistant Integration (REQ-005)¶

Variable	Standard	Pflicht	Beschreibung
`HA_URL`	—	Nein	Home-Assistant-Basis-URL, z. B. `http://homeassistant.local:8123`
`HA_ACCESS_TOKEN`	—	Nein	Long-Lived Access Token aus Home Assistant
`HA_TIMEOUT`	`10`	Nein	HTTP-Timeout für HA-Anfragen (Sekunden)

Rate Limiting¶

Variable	Standard	Pflicht	Beschreibung
`RATE_LIMIT_AUTH`	`20/minute`	Nein	Rate-Limit für Authentifizierungsendpunkte
`RATE_LIMIT_GENERAL`	`100/minute`	Nein	Rate-Limit für allgemeine API-Endpunkte

Format: [anzahl]/[einheit] — Einheiten: second, minute, hour, day

Uploads¶

Variable	Standard	Pflicht	Beschreibung
`UPLOAD_DIR`	`uploads/tasks`	Nein	Verzeichnis für Datei-Uploads (relativ zum Backend-Arbeitsverzeichnis)

Verschachtelte Konfiguration (GBIF)¶

GBIF-Einstellungen können über den Unterstrich-Doppelpunkt-Delimiter verschachtelt werden:

Variable	Standard	Beschreibung
`GBIF__BASE_URL`	`https://api.gbif.org/v1`	GBIF-API-Basis-URL
`GBIF__RATE_LIMIT_PER_MINUTE`	`60`	Anfragen pro Minute an GBIF
`GBIF__HTTP_TIMEOUT`	`30`	Timeout für GBIF-Anfragen (Sekunden)

Vollständiges .env-Beispiel¶

# Datenbank
ARANGO_ROOT_PASSWORD=sicheres-root-passwort
ARANGODB_HOST=arangodb
ARANGODB_PORT=8529
ARANGODB_DATABASE=kamerplanter
ARANGODB_USERNAME=root
ARANGODB_PASSWORD=sicheres-root-passwort

# Cache / Queue
REDIS_URL=redis://valkey:6379/0

# Sicherheit
JWT_SECRET_KEY=erzeugen-mit-openssl-rand-hex-32
REQUIRE_EMAIL_VERIFICATION=false

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

# Betriebsmodus
KAMERPLANTER_MODE=full
DEBUG=false

# E-Mail (Entwicklung)
EMAIL_ADAPTER=console

# Optionale externe APIs
PERENUAL_API_KEY=
HA_URL=
HA_ACCESS_TOKEN=

Haeufige Fragen¶

Kann ich Umgebungsvariablen in Kubernetes als Secrets hinterlegen?

Ja. Verwenden Sie Kubernetes Secrets für sensible Werte (ARANGODB_PASSWORD, JWT_SECRET_KEY) und referenzieren Sie sie im Deployment-Manifest über valueFrom.secretKeyRef.

Wo kann ich prüfen, welche Werte das Backend tatsächlich verwendet?

Mit DEBUG=true loggt das Backend beim Start alle geladenen Einstellungen. Alternativ im Container:

docker compose exec backend python -c "from app.config.settings import settings; print(settings.model_dump())"

Passwörter und Secrets werden dabei nicht im Klartext angezeigt.