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

Feature Flags (auch Feature Toggles) schalten einzelne Funktionen einer Anwendung zur Laufzeit ein oder aus, ohne neuen Code auszurollen. Unleash ist eine verbreitete Open-Source-Plattform dafür (AGPL-3.0) mit Weboberfläche, REST-API, 15 offiziellen SDKs sowie Strategien für schrittweise Rollouts, A/B-Tests, Kill Switches und Nutzersegmente. Diese Anleitung zeigt die Installation per Docker Compose auf einem Linux-Host, einer VM oder einem NAS mit Docker.

Voraussetzungen

1. Docker Engine >= 20.10 mit Docker Compose Plugin v2 (docker compose, kein Bindestrich), Installation siehe Docker und Docker Compose auf Linux installieren.
2. Linux-Host, VM oder NAS mit Docker-Support (linux/amd64 oder linux/arm64, laut Docker Hub beide für 8.2.0 verfügbar).
3. 1 CPU-Kern, mindestens 512 MB freier RAM für beide Container (empfohlen 1 GB, im Test belegten sie zusammen rund 185 MiB), mindestens 1 GB freier Speicherplatz für Images und Datenbank-Volume.
4. Internetverbindung für den einmaligen Image-Pull (komprimiert Unleash-Server ca. 95 MB, PostgreSQL 15 ca. 160 MB).
5. Für den Produktivbetrieb ein Reverse Proxy mit TLS, etwa Caddy oder Traefik.
6. curl für die Prüfschritte.

Schritt 1: Projektordner und Verzeichnisstruktur anlegen

Alle Konfigurationsdateien liegen in einem Ordner, üblich ist /opt/unleash/, ~/unleash/ funktioniert genauso. Unter /opt brauchen Sie sudo und übergeben den Ordner danach Ihrem Benutzer:

sudo mkdir -p /opt/unleash
sudo chown "$USER": /opt/unleash
cd /opt/unleash

Hier entstehen .env (Secrets) und compose.yaml (Stack-Definition). Unleash selbst braucht kein Datenverzeichnis, der gesamte Zustand liegt in PostgreSQL. Hintergrund zu Volumes: Docker-Netzwerke und Volumes richtig nutzen.

Verifizieren: Das Verzeichnis existiert und gehört Ihrem Benutzer.

ls -la /opt/unleash

Erwartete Ausgabe: leeres Verzeichnis, Besitzer ist Ihr Benutzer.

Schritt 2: .env-Datei mit Secrets anlegen

Passwörter und variable Werte stehen in der .env. So bleibt die compose.yaml frei von Secrets und kann in ein Git-Repository, die .env nicht. Erzeugen Sie zuerst ein zufälliges Datenbankpasswort:

openssl rand -hex 24

Legen Sie dann die .env an und ersetzen Sie die Platzhalter:

# /opt/unleash/.env
# Datenbankpasswort, wird in DATABASE_URL und POSTGRES_PASSWORD verwendet
POSTGRES_PASSWORD=IHR_SICHERES_PASSWORT

# Unleash-Admin, wirkt nur beim allerersten Start (danach Passwort im UI ändern)
UNLEASH_ADMIN_USER=admin
UNLEASH_ADMIN_PASSWORD=unleash4all

# Öffentlich erreichbare Adresse (für korrekte Links in UI und Webhooks)
UNLEASH_URL=http://localhost:4242

Nur Ihr Benutzer soll die Datei lesen können:

chmod 600 /opt/unleash/.env

Wichtig: Die compose.yaml setzt POSTGRES_PASSWORD auch in die DATABASE_URL ein. Verwenden Sie deshalb nur Buchstaben und Ziffern (wie bei openssl rand -hex 24), Zeichen wie /, + oder @ müssten in der URL kodiert werden.

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 sprechen über das interne Docker-Netzwerk, nach außen öffnet nur der Unleash-Server Port 4242. PostgreSQL ist nur intern erreichbar.

Eckdaten auf einen Blick:

Erstellen Sie die compose.yaml:

services:
  web:
    image: unleashorg/unleash-server:8.2.0
    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: "${UNLEASH_URL:-http://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:

Der Hostname in der DATABASE_URL muss dem Service-Namen entsprechen, hier db, nicht localhost. condition: service_healthy startet Unleash erst, wenn PostgreSQL bereit ist. Der feste Tag 8.2.0 verhindert unbeabsichtigte Major-Updates. Auf Docker Hub heißen die Tags ohne „v“ (8.2.0, 8.2, 8), ein Tag v8.2.0 existiert nicht.

Verifizieren:

cat /opt/unleash/compose.yaml

Zusätzlich prüft docker compose config -q die Datei. Ohne Ausgabe ist sie gültig, bei einem Fehler nennt der Befehl Zeile und Ursache.

Schritt 4: Stack starten

Starten Sie den Stack im Hintergrund:

cd /opt/unleash
docker compose up -d

Docker lädt die Images, legt Netzwerk und Volume an und startet die Container. Der Unleash-Server wartet auf den Healthcheck der Datenbank. Im Test waren beide Container nach rund 45 Sekunden (healthy).

Status prüfen:

docker compose ps

Erwartete Ausgabe nach vollständigem Start:

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

Beide Container müssen den Status (healthy) zeigen. Bei (starting) läuft die Initialisierung noch, warten Sie 30 Sekunden und prüfen Sie erneut.

Health-Endpunkt direkt abfragen:

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

Erwartete Antwort:

{"health":"GOOD"}

Bei Fehlern helfen 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

Öffnen Sie http://localhost:4242 (oder die IP Ihres Hosts) im Browser und melden Sie sich an:

1. Benutzername: admin
2. Passwort: unleash4all

Ändern Sie das Passwort sofort über Ihr Benutzerprofil (Change password), admin/unleash4all ist öffentlich bekannt. Im Test lehnte Unleash 8.2.0 ein schwaches Passwort mit OwaspValidationError ab: mindestens 10 Zeichen, Groß- und Kleinbuchstaben, Ziffer und Sonderzeichen. Danach lieferte die Anmeldung mit dem alten Passwort 401.

Flags legen Sie in Projekten an. Zustand und Aktivierungsstrategie (Prozent-Rollout, Nutzer-ID, IP usw.) konfigurieren Sie je Umgebung. Eine frische Installation bringt im Projekt „Default“ die Umgebungen development und production mit.

Für SDKs brauchen Sie API-Tokens. Erstellen Sie unter Admin > API access:

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. Er liefert nur Flag-Zustände, 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 nur für lokale Entwicklung gedacht.

Verifizieren: Die Anmeldung mit dem neuen Passwort gelingt, das Projekt „Default“ ist sichtbar. curl -s -H "Authorization: IHR_CLIENT_TOKEN" http://localhost:4242/api/client/features liefert JSON mit Ihren Flags, ohne Token antwortet die API mit 401.

Schritt 6: Reverse Proxy und HTTPS (Produktion)

Port 4242 liefert reines HTTP. Ist Unleash über das Internet erreichbar, muss ein Reverse Proxy mit TLS davor, zum Beispiel:

1. Caddy (automatisches HTTPS über Let's Encrypt), siehe Caddy als Reverse Proxy einrichten.
2. Traefik (Docker-nativ, per Labels), siehe Traefik als Docker-Reverse-Proxy mit automatischem HTTPS.
3. nginx mit Certbot, siehe nginx als Reverse Proxy mit TLS manuell einrichten.

Mit eigener Domain (z. B. unleash.example.com) tragen Sie die vollständige öffentliche Adresse ohne Port 4242 in die .env ein:

UNLEASH_URL=https://unleash.example.com

Danach übernehmen Sie die Änderung:

cd /opt/unleash
docker compose up -d

Beschränken Sie außerdem in der compose.yaml die Port-Freigabe auf Localhost, sobald der Reverse Proxy ü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

Für ein Update tragen Sie den neuen Tag in die compose.yaml ein (Release Notes vorher lesen) und führen aus:

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

Docker lädt das neue Image und erstellt nur den web-Container neu, die Datenbank bleibt erhalten. Danach Healthcheck prüfen:

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

Nutzen Sie keine automatischen Updates mit :latest (etwa per Watchtower), sonst kann unbemerkt eine neue Major-Version starten.

Backup: Alle Daten liegen im PostgreSQL-Volume unleash-db-data, ein regelmäßiges pg_dump sichert alles. Im Test umfasste der Abzug 108 Tabellen, ein Restore in eine leere Testdatenbank enthielt das angelegte Flag wieder.

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

Automatisierte PostgreSQL-Backups beschreibt PostgreSQL pg_dump und pg_restore: Backup und Migration per Kommandozeile.

Verifizieren: Nach dem Update zeigt docker compose ps beide Container als (healthy). Die Backup-Datei ist nicht leer und enthält Tabellendefinitionen (grep -c "CREATE TABLE" liefert über 100):

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

Troubleshooting / Typische Fehler

1. „could not connect to database“ beim ersten Start: PostgreSQL ist noch nicht bereit. Lösung: docker compose restart web. Dauerhaft hilft ein längerer start_period im Datenbank-Healthcheck, etwa 30 Sekunden.
2. Unleash-Container bleibt bei (starting) oder bricht ab: Logs prüfen: 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: sudo ss -tlnp | grep 4242 zeigt den belegenden Prozess. Alternativ ändern Sie den Host-Port, z. B. "14242:4242".
4. PostgreSQL-Volume fehlt oder wurde gelöscht: Flags, Nutzer und Konfiguration sind verloren, eine Wiederherstellung geht nur aus dem pg_dump. Prüfen Sie mit docker volume ls | grep unleash, ob das Volume existiert.
5. Admin-Passwort vergessen: Ein anderer Administrator setzt es unter Admin > Users zurück. Die Variable UNLEASH_ADMIN_PASSWORD hilft nicht: Im Test blieb eine Änderung in der .env nach dem Erststart ohne Wirkung (Anmeldung 401). Das Image 8.2.0 enthält auch kein npx, ein Aufruf von npx im Container scheitert mit executable file not found. Legen Sie deshalb früh einen zweiten Administrator an.
6. POSTGRES_HOST_AUTH_METHOD=trust in der compose.yaml: Das offizielle Demo-Compose im Unleash-Repository erlaubt damit jedem Prozess im Docker-Netzwerk passwortlose Datenbankverbindungen. Die hier gezeigte Konfiguration verzichtet bewusst darauf, nutzen Sie es nie produktiv.
7. unleash-docker Repository (archiviert) als Referenz verwendet: Das GitHub-Repository github.com/Unleash/unleash-docker ist archiviert (letzter Commit November 2022) und veraltet. Maßgeblich ist das Haupt-Repository github.com/Unleash/unleash.

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 Lizenz brauchen Sie nur für Enterprise-Funktionen wie SSO per SAML/OIDC und erweiterte Rollenmodelle.

Welche Datenbank wird unterstützt?

Ausschließlich PostgreSQL. MySQL, SQLite, MariaDB und andere Datenbanken werden nicht unterstützt. Das offizielle Compose-Beispiel nutzt PostgreSQL 15, ebenso diese Anleitung.

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, das Image dieser Anleitung. Unleash Edge (unleashorg/unleash-edge) ist ein separater Proxy zwischen Server und SDKs. 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 ein offizielles SDK (u. a. Node.js, Python, Java, Go, .NET, PHP, Ruby) oder die REST-API. Das SDK holt die Flag-Konfiguration und wertet sie lokal aus. Das senkt die Latenz, und Ihre Anwendung läuft auch bei kurzem Ausfall des Unleash-Servers weiter. Der Zugriff erfolgt über einen Backend-API-Token (Typ: CLIENT).

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

Ja. Zustand und Strategie legen Sie je Flag und Umgebung fest, ohne getrennte Instanzen (siehe Schritt 5). Weitere Umgebungen wie staging legen Sie selbst an.

Welche Aktivierungsstrategien bietet Unleash?

Eingebaut sind unter anderem Prozent-Rollout (Canary Deployment), Nutzer-ID-Targeting sowie IP- und Hostname-Filter, dazu eigene Strategien.

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

Über Ihr Benutzerprofil (Change password) in der Web-UI. Alternativ setzen Sie UNLEASH_ADMIN_PASSWORD in der .env vor dem allerersten Start auf einen sicheren Wert. Danach hat die Variable keine Wirkung mehr, das bestätigte der Test.

Fazit

Unleash ist aktiv gepflegt und bringt Feature-Flag-Verwaltung ohne Cloud-Abhängigkeit. Der geringe Ressourcenbedarf und die schlanke Compose-Konfiguration passen auch zu kleinen Teams. Für den Produktivbetrieb zählen drei Punkte: Standardpasswort sofort ändern, POSTGRES_HOST_AUTH_METHOD=trust meiden und einen Reverse Proxy mit TLS vorschalten.

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 auf GitHub | Unleash-Dokumentation | unleashorg/unleash-server auf Docker Hub

Passende Anleitungen auf S-EDV

1. PostgreSQL schließt elf Sicherheitslücken in den Versionen 14 bis 18
2. netcup Local Block Storage bestellen, einrichten und unter Linux einbinden