Unleash mit Docker installieren: Open-Source-Feature-Flag-Plattform selbst hosten

Feature Flags – auch Feature Toggles genannt – erlauben es dir, einzelne Funktionen deiner Anwendung zur Laufzeit ein- und auszuschalten, ohne einen neuen Code-Stand in Produktion zu deployen. Unleash ist die führende Open-Source-Plattform für genau dieses Muster: Mit über 13.600 GitHub-Stars und mehr als 10 Millionen Docker-Hub-Pulls hat sich das Projekt als Standard für selbst hostbare Feature-Flag-Verwaltung etabliert. Du erhältst eine vollständige Web-UI, eine REST-API, SDKs für über 15 Programmiersprachen (JavaScript, Python, Java, Go, .NET, PHP, Ruby und weitere) sowie Unterstützung für Canary Deployments, A/B-Tests, Kill Switches und Nutzer-Segmentierung – lizenziert unter AGPL-3.0, also kostenlos nutzbar. Diese Anleitung führt dich Schritt für Schritt durch die Installation per Docker Compose auf einem beliebigen Linux-Host: Ubuntu, Debian, eine VM oder ein NAS mit Docker-Support.

Voraussetzungen

1. Docker Engine >= 20.10 mit Docker Compose Plugin v2 (docker compose, kein Bindestrich) – wie du beides auf Ubuntu/Debian installierst, zeigt die Anleitung Docker und Docker Compose auf Linux installieren.
2. Linux-Host, VM oder NAS mit Docker-Support (linux/amd64 oder linux/arm64 – läuft auch auf Apple Silicon, Raspberry Pi und AWS Graviton).
3. Mindestens 512 MB freier RAM für beide Container (empfohlen: 1 GB+); mindestens 1 GB freier Speicherplatz für Images und Datenbank-Volume.
4. Internetverbindung für den einmaligen Image-Pull (Unleash-Server ca. 86 MB, PostgreSQL 15 ca. 250 MB).
5. Für den Produktivbetrieb: ein Reverse Proxy mit TLS – empfehlenswert sind Caddy oder Traefik.
6. Ein Texteditor sowie curl oder wget für die Verifikationsschritte.

Schritt 1: Projektordner und Verzeichnisstruktur anlegen

Alle Konfigurationsdateien kommen in einen gemeinsamen Ordner. Wähle einen Pfad, der für dich sinnvoll ist – /opt/unleash/ ist ein gebräuchlicher Ort für systemweite Dienste, ~/unleash/ funktioniert genauso:

mkdir -p /opt/unleash
cd /opt/unleash

In diesem Ordner legst du im nächsten Schritt zwei Dateien an: .env (Secrets und Konfiguration) sowie compose.yaml (Stack-Definition). Unleash selbst benötigt kein zusätzliches Volume im Dateisystem – der gesamte Zustand liegt in PostgreSQL. Ausführlichere Infos zu Docker-Volumes findest du in der Grundlagenanleitung Docker-Netzwerke und Volumes richtig nutzen.

Verifizieren: Das Verzeichnis existiert und du hast Schreibrechte.

ls -la /opt/unleash

Erwartete Ausgabe: Das Verzeichnis ist leer, Besitzer ist dein Benutzer.

Schritt 2: .env-Datei mit Secrets anlegen

Lege alle Passwörter und variablen Werte in einer .env-Datei ab – so bleibt die compose.yaml frei von Secrets und kann sicher in ein Git-Repository eingecheckt werden (die .env selbst natürlich nicht).

Generiere zunächst ein sicheres Passwort (mindestens 16 Zeichen, zufällig):

openssl rand -base64 24

Lege dann die .env-Datei an und ersetze die Platzhalterwerte:

# /opt/unleash/.env
# Datenbankpasswort – dasselbe in DATABASE_URL und POSTGRES_PASSWORD
POSTGRES_PASSWORD=DEIN_SICHERES_PASSWORT_HIER

# Unleash Admin-Zugangsdaten (nach erstem Login sofort im UI ändern!)
UNLEASH_ADMIN_USER=admin
UNLEASH_ADMIN_PASSWORD=unleash4all

# Öffentlich erreichbare URL (für korrekte Links in UI und Webhooks)
UNLEASH_HOST=localhost

Setze die Dateiberechtigungen so, dass nur dein Benutzer die Datei lesen kann:

chmod 600 /opt/unleash/.env

Wichtig: Der Wert von POSTGRES_PASSWORD muss identisch mit dem Passwort in der DATABASE_URL in der compose.yaml sein. Ändere ihn an keiner Stelle separat.

Verifizieren:

ls -la /opt/unleash/.env

Erwartete Ausgabe: -rw------- – nur der Besitzer hat Lese- und Schreibrecht.

Schritt 3: compose.yaml erstellen

Der Stack besteht aus zwei Services: dem Unleash-Server (web) und PostgreSQL (db). Beide kommunizieren über das interne Docker-Netzwerk; nach außen öffnet nur der Unleash-Server Port 4242. PostgreSQL ist ausschließlich intern per expose erreichbar.

Eckdaten auf einen Blick:

Erstelle nun die compose.yaml:

services:
  web:
    image: unleashorg/unleash-server:latest
    container_name: unleash
    restart: unless-stopped
    ports:
      - "4242:4242"
    environment:
      DATABASE_URL: "postgres://unleash_user:${POSTGRES_PASSWORD}@db:5432/unleash"
      DATABASE_SSL: "false"
      LOG_LEVEL: "warn"
      UNLEASH_URL: "http://${UNLEASH_HOST:-localhost}:4242"
      UNLEASH_DEFAULT_ADMIN_USERNAME: "${UNLEASH_ADMIN_USER:-admin}"
      UNLEASH_DEFAULT_ADMIN_PASSWORD: "${UNLEASH_ADMIN_PASSWORD:-unleash4all}"
    depends_on:
      db:
        condition: service_healthy
    healthcheck:
      test: wget --no-verbose --tries=1 --spider http://localhost:4242/health || exit 1
      interval: 5s
      timeout: 30s
      retries: 10
      start_period: 20s

  db:
    image: postgres:15
    container_name: unleash-db
    restart: unless-stopped
    expose:
      - "5432"
    environment:
      POSTGRES_DB: "unleash"
      POSTGRES_USER: "unleash_user"
      POSTGRES_PASSWORD: "${POSTGRES_PASSWORD}"
    volumes:
      - unleash-db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD", "pg_isready", "--username=unleash_user", "--host=127.0.0.1", "--port=5432"]
      interval: 2s
      timeout: 30s
      retries: 5
      start_period: 10s

volumes:
  unleash-db-data:

Ein paar wichtige Details zur Konfiguration: Der Hostname in der DATABASE_URL muss exakt dem Service-Namen im Compose-Stack entsprechen – hier db, nicht localhost. Das depends_on mit condition: service_healthy stellt sicher, dass PostgreSQL vollständig bereit ist, bevor der Unleash-Server startet. Der start_period von 20 Sekunden gibt PostgreSQL beim allerersten Start (Datenbankinitialisierung) ausreichend Zeit. Für den Produktivbetrieb empfiehlt es sich, den Image-Tag von :latest auf einen fixen Versions-Tag wie unleashorg/unleash-server:v8.0.0 zu wechseln, um unerwartete Breaking Changes durch Auto-Updates zu vermeiden.

Verifizieren:

cat /opt/unleash/compose.yaml

Beide Services, das Volume und die Healthchecks müssen korrekt eingerückt und vollständig sichtbar sein.

Schritt 4: Stack starten

Starte alle Container im Hintergrund:

cd /opt/unleash
docker compose up -d

Docker lädt beim ersten Start die Images herunter (insgesamt ca. 336 MB), erstellt das Netzwerk und das Volume, und startet die Container. Der Unleash-Server wartet auf den Healthcheck der Datenbank, bevor er hochfährt – das dauert beim ersten Start typischerweise 30–60 Sekunden.

Prüfe den Status der Container:

docker compose ps

Erwartete Ausgabe nach vollständigem Start:

NAME          IMAGE                              STATUS
unleash       unleashorg/unleash-server:latest   Up X minutes (healthy)
unleash-db    postgres:15                        Up X minutes (healthy)

Beide Container müssen den Status (healthy) zeigen. Solange noch (starting) angezeigt wird, läuft die Initialisierung – warte weitere 30 Sekunden und führe docker compose ps erneut aus.

Überprüfe den Unleash-Healthcheck-Endpunkt direkt:

curl -s http://localhost:4242/health

Erwartete Antwort:

{"health":"GOOD"}

Falls du noch Fehler siehst, wirf einen Blick in die Logs:

docker compose logs web
docker compose logs db

Verifizieren: docker compose ps zeigt beide Container als (healthy), und curl http://localhost:4242/health gibt {"health":"GOOD"} zurück.

Schritt 5: Erste Einrichtung im Browser

Öffne http://localhost:4242 (oder ersetze localhost durch die IP deines Hosts) im Browser. Du landest auf dem Unleash-Login:

1. Benutzername: admin
2. Passwort: unleash4all

Nach dem ersten Login wirst du aufgefordert, das Standard-Passwort zu ändern. Tu das sofort – admin/unleash4all ist öffentlich bekannt und darf nie im Produktivbetrieb verbleiben. Unleash erzwingt dabei von Haus aus ein Mindestmaß an Passwortstärke.

Im nächsten Schritt richtest du dein erstes Projekt und die erste Feature-Flag-Umgebung ein. Unleash unterstützt native Multi-Environment-Konfiguration: Für jeden Feature Flag kannst du den Zustand (aktiviert/deaktiviert) und die Aktivierungsstrategie (Prozentsatz-Rollout, Nutzer-ID-Targeting, IP-Filter usw.) pro Umgebung (z. B. development, staging, production) separat konfigurieren.

Für die SDK-Integration benötigst du API-Tokens. Navigiere zu Admin > API access und erstelle dort:

1. Einen Backend-SDK-Token (Typ: CLIENT) für serverseitige SDKs (Node.js, Python, Java, Go usw.).
2. Optional einen Frontend-SDK-Token (Typ: FRONTEND) für Browser- und Mobile-Apps – dieser gibt nur die Flag-Zustände zurück, nicht die vollständige Konfiguration.

Die Demo-Tokens unleash-insecure-api-token und unleash-insecure-frontend-api-token, die per INIT_BACKEND_API_TOKENS / INIT_FRONTEND_API_TOKENS automatisch erzeugt werden können, sind ausschließlich für lokale Entwicklung gedacht – das Wort „insecure" im Namen ist kein Zufall.

Verifizieren: Du bist eingeloggt, hast das Passwort geändert und siehst das Unleash-Dashboard mit einem Standardprojekt. Unter Admin > API access sind API-Tokens erstellt.

Schritt 6: Reverse Proxy und HTTPS (Produktion)

Unleash hat keine eingebaute TLS-Unterstützung – Port 4242 liefert reines HTTP. Für den Produktivbetrieb, bei dem Unleash über das Internet erreichbar ist, muss ein Reverse Proxy vorgeschaltet werden. Empfehlenswert sind:

1. Caddy (automatisches HTTPS via Let's Encrypt, minimale Konfiguration) – siehe Caddy als Reverse Proxy einrichten.
2. Traefik (Docker-nativ, Labels-basiert) – siehe Traefik als Docker-Reverse-Proxy mit automatischem HTTPS.
3. nginx mit Certbot – siehe nginx als Reverse Proxy mit TLS manuell einrichten.

Sobald du eine öffentliche Domain für Unleash hast (z. B. unleash.example.com), passe die UNLEASH_HOST in der .env an:

UNLEASH_HOST=unleash.example.com

Und starte den Stack neu:

cd /opt/unleash
docker compose up -d

Außerdem solltest du in der compose.yaml die Port-Freigabe auf Localhost einschränken, sobald der Reverse Proxy den Traffic übernimmt:

ports:
  - "127.0.0.1:4242:4242"

Verifizieren: curl -I https://unleash.example.com/health gibt HTTP/2 200 zurück. Das TLS-Zertifikat ist gültig.

Schritt 7: Updates und Backup

Um Unleash auf die neueste Version zu aktualisieren, reichen zwei Befehle:

cd /opt/unleash
docker compose pull
docker compose up -d

Docker lädt das neue Image und startet nur den web-Container neu; die Datenbank bleibt dabei erhalten. Prüfe nach dem Update erneut den Healthcheck:

docker compose ps
curl -s http://localhost:4242/health

Für den Produktivbetrieb empfiehlt es sich, in der compose.yaml einen fixen Image-Tag zu verwenden (z. B. unleashorg/unleash-server:v8.0.0) und Updates kontrolliert einzuspielen – nicht :latest in Kombination mit automatischen Updates via Watchtower.

Backup: Da alle Daten ausschließlich im PostgreSQL-Volume unleash-db-data liegen, reicht ein regelmäßiges pg_dump für ein vollständiges Backup:

docker exec unleash-db pg_dump -U unleash_user unleash > /opt/unleash/backup_$(date +%Y%m%d).sql

Eine ausführliche Anleitung zu automatisierten PostgreSQL-Backups findest du unter PostgreSQL pg_dump und pg_restore: Backup und Migration per Kommandozeile.

Verifizieren: Nach dem Update zeigt docker compose ps weiterhin beide Container als (healthy). Die Backup-Datei existiert und ist nicht leer:

ls -lh /opt/unleash/backup_*.sql

Troubleshooting / Typische Fehler

1. „could not connect to database" beim ersten Start: Race-Condition – PostgreSQL ist noch nicht vollständig bereit. Lösung: docker compose restart web ausführen. Mittel- bis langfristig hilft es, den start_period im Unleash-Healthcheck auf 30–40 Sekunden zu erhöhen.
2. Unleash-Container bleibt bei (starting) oder bricht ab: Sieh dir die Logs an: docker compose logs web. Häufigste Ursache: falsches Passwort in der DATABASE_URL (stimmt nicht mit POSTGRES_PASSWORD überein) oder ein Tippfehler im Hostnamen (localhost statt db).
3. Port 4242 bereits belegt: Prüfe mit ss -tlnp | grep 4242, welcher Prozess den Port nutzt, oder ändere den Host-Port in der compose.yaml auf einen freien Port, z. B. "14242:4242".
4. PostgreSQL-Volume fehlt oder wurde gelöscht: Alle Feature-Flags, Nutzer und Konfigurationen sind verloren. Ohne unleash-db-data:/var/lib/postgresql/data in der compose.yaml persistiert nichts. Prüfe mit docker volume ls | grep unleash, ob das Volume existiert.
5. Admin-Passwort vergessen: Das Passwort lässt sich über den Passwort-Änderungs-Dialog in der UI zurücksetzen (als anderer Admin) oder per CLI: docker exec unleash npx unleash-cli admin reset-password --username admin --password NeuesPasswort123!
6. POSTGRES_HOST_AUTH_METHOD=trust in der compose.yaml: Diese Einstellung aus dem offiziellen Demo-Repository erlaubt jedem Prozess im Docker-Netzwerk passwortlose Verbindungen zur Datenbank. Sie ist in der hier gezeigten Konfiguration bewusst nicht enthalten. Verwende sie niemals in einer produktiven Umgebung.
7. unleash-docker Repository (archiviert) als Referenz verwendet: Das GitHub-Repository github.com/Unleash/unleash-docker wurde im Dezember 2022 archiviert und enthält veraltete Konfigurationen. Verwende ausschließlich das Haupt-Repository github.com/Unleash/unleash als Referenz.

Häufige Fragen

Brauche ich eine Lizenz für den selbst-gehosteten Betrieb?

Nein. Die Open-Source-Edition von Unleash ist unter AGPL-3.0 lizenziert und kann kostenlos selbst gehostet werden. Eine kommerzielle Enterprise-Lizenz ist nur für spezifische Enterprise-Features erforderlich – darunter SSO, SAML/OIDC-Integration und erweiterte Rollenmodelle.

Welche Datenbank wird unterstützt?

Ausschließlich PostgreSQL. MySQL, SQLite, MariaDB und andere Datenbanken werden nicht unterstützt. Offiziell empfohlen und getestet ist PostgreSQL 15, das auch in dieser Anleitung verwendet wird.

Was ist der Unterschied zwischen Unleash Server und Unleash Edge?

Unleash Server (unleashorg/unleash-server) ist die Kernplattform mit Web-UI, REST-API und Datenbank-Backend – das ist das Image dieser Anleitung. Unleash Edge (unleashorg/unleash-edge) ist ein separater, hochperformanter Proxy-Layer, der zwischen Server und SDKs geschaltet wird. Edge ist für Szenarien mit sehr hoher Last (über 1.000 Flag-Evaluierungen pro Sekunde) gedacht und für normale Self-Hosting-Setups nicht notwendig.

Wie integriere ich Unleash in meine Anwendung?

Über eines der offiziellen SDKs (für JavaScript/Node.js, Python, Java, Go, .NET, PHP, Ruby und weitere) oder direkt über die REST-API. Das SDK verbindet sich mit dem Unleash-Server, holt die Feature-Flag-Konfiguration und wertet sie lokal aus – das minimiert die Latenz und macht deine Anwendung unabhängig von der Verfügbarkeit des Unleash-Servers. Der Zugriff erfolgt über einen Backend-API-Token (Typ: CLIENT).

Kann Unleash mit mehreren Umgebungen arbeiten (dev/staging/prod)?

Ja, Multi-Environment-Konfiguration ist ein natives Feature. Für jeden Feature Flag kannst du Zustand (aktiviert/deaktiviert) und Aktivierungsstrategie pro Umgebung separat festlegen – ohne separate Unleash-Instanzen betreiben zu müssen.

Welche Aktivierungsstrategien bietet Unleash?

Unleash kommt mit mehreren eingebauten Strategien: Prozentsatz-Rollout (klassisches Canary Deployment), Nutzer-ID-Targeting, IP-Adressen-Filter, Hostname-Filter sowie Custom-Strategie-Plugins für eigene Logik. Kombiniert mit der Umgebungssegmentierung lässt sich so nahezu jedes Release-Muster abbilden.

Wie ändere ich das Admin-Passwort nach dem ersten Start?

Entweder über die Web-UI unter Admin > Profile > Change Password, oder du setzt die Umgebungsvariable UNLEASH_DEFAULT_ADMIN_PASSWORD in der .env auf einen sicheren Wert, bevor du den Container zum ersten Mal startest. Nach dem ersten Start hat diese Variable keinen Effekt mehr – nutze dann den Passwort-Änderungs-Dialog in der UI.

Fazit

Unleash ist ein ausgereiftes, aktiv gepflegtes Open-Source-Projekt (811 Releases, Stand Juni 2026) und die erste Wahl, wenn du Feature-Flag-Management ohne Cloud-Abhängigkeit und ohne Vendor-Lock-in einführen möchtest. Der geringe RAM-Bedarf und die unkomplizierte Docker-Compose-Konfiguration machen Unleash auch für kleine Teams und KMU attraktiv. Der wichtigste Hinweis für den Produktivbetrieb: Standard-Passwort sofort ändern, POSTGRES_HOST_AUTH_METHOD=trust konsequent meiden und einen Reverse Proxy mit TLS vorschalten – dann ist der Weg von der lokalen Entwicklung zu einem sicheren Produktionssetup ein kleiner Schritt.

Weiterführende Anleitungen und Quellen

1. Docker und Docker Compose auf Linux installieren (Ubuntu/Debian): die Self-Hosting-Grundlage
2. Traefik als Docker-Reverse-Proxy mit automatischem HTTPS einrichten
3. Caddy als Reverse Proxy einrichten: Anfänger-Anleitung mit automatischem HTTPS
4. PostgreSQL pg_dump und pg_restore: Anleitung für Backup und Migration per Kommandozeile
5. Docker Compose absichern: Secrets, Healthchecks, Non-Root und Read-Only für den Produktivbetrieb
6. GitLab CE mit Docker installieren: Vollständige DevOps-Plattform

Offizielle Quellen: Unleash GitHub Repository (Haupt-Repo): github.com/Unleash/unleash | Unleash Dokumentation: docs.getunleash.io | unleashorg/unleash-server auf Docker Hub: hub.docker.com/r/unleashorg/unleash-server

Passende Anleitungen auf S-EDV

1. PCI DSS 4.0.1: Checkout-Skripte als Sicherheitsrisiko - was Admins jetzt prüfen
2. PostgreSQL schließt elf Sicherheitslücken in den Versionen 14 bis 18
3. netcup Local Block Storage bestellen, einrichten und unter Linux einbinden