Umgebungsvariablen

Umgebungsvariablen sind der empfohlene Weg, um Anwendungen zu konfigurieren — ohne Werte ins Repository einzuchecken.

Typen

Typ	Verfügbar	Beispiel
Build-Zeit	Während `docker build`	`NEXT_PUBLIC_API_URL`, `VITE_APP_NAME`
Laufzeit	Im laufenden Container	`DATABASE_URL`, `JWT_SECRET`, `LOG_LEVEL`

Die meisten Variablen sind Laufzeit-Variablen. Build-Zeit-Variablen braucht ihr nur, wenn euer Build-Prozess Werte direkt einbettet (z. B. React/Vite mit VITE_*-Variablen).

Variablen setzen

Via Oberfläche

Anwendung öffnen → “Umgebungsvariablen”
“Variable hinzufügen” → Key und Value eintragen
Bei sensiblen Werten: “Geheimnis”-Toggle aktivieren
“Speichern” — beim nächsten Deployment aktiv

Via API

# Variablen einer Anwendung aktualisieren (PATCH überschreibt den kompletten Satz)
curl -s -X PATCH https://coolai.btc-ag.cloud/api/v1/applications/<app-uuid> \
  -H "Authorization: Bearer $COOLIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "environment_variables": "DATABASE_URL=postgresql://user:pass@host:5432/db\nLOG_LEVEL=info\nAPP_ENV=production"
  }'

Secrets — sicherer Umgang

Secrets sind Variablen, deren Werte besonders sensibel sind (Passwörter, API-Keys, Private Keys).

Empfehlungen:

Secrets niemals in Git einchecken (.gitignore für .env-Dateien)
Secrets niemals in Logs ausgeben
Secrets rotieren, wenn Zugang eines Teammitglieds erlischt
Nur so viele Secrets wie nötig — je Anwendung nur die tatsächlich benötigten Werte

# Beispiel: .env-Datei (lokal / für Entwicklung, niemals committen!)
DATABASE_URL="postgresql://dev:devpass@localhost:5432/myapp"
JWT_SECRET="lokaler-dev-secret-nicht-produktionsreif"

Best Practices

12-Factor-App-Prinzip

Folgt dem 12-Factor-App-Prinzip: Alle Konfiguration, die sich zwischen Umgebungen unterscheidet, kommt aus Umgebungsvariablen — nicht aus dem Code.

# Gut: Konfiguration aus der Umgebung
const dbUrl = process.env.DATABASE_URL;

# Schlecht: Konfiguration im Code
const dbUrl = "postgresql://user:pass@prod-server:5432/db";

Unterschied Entwicklung / Produktion

Umgebung	Empfehlung
Lokale Entwicklung	`.env`-Datei (niemals committen)
Staging / Produktion	Variablen in der Plattform hinterlegen

`.env.example` für Dokumentation

Checkt eine .env.example ins Repository ein, die alle Variablen mit Erklärungen, aber ohne echte Werte enthält:

# .env.example — In Git einchecken!
# Beschreibung: Verbindungsstring zur Datenbank
DATABASE_URL=

# API-Schlüssel für externen Service
EXTERNAL_API_KEY=

# Loglevel: debug | info | warn | error
LOG_LEVEL=info

Variablen im Build-Log

Variablen, die als Geheimnis markiert sind, werden in Build-Logs automatisch maskiert (***).