---
title: "Unleash mit Docker installieren: Open-Source-Feature-Flag-Plattform selbst hosten"
date: 2026-07-05T07:19:15+02:00
modified: 2026-11-10T18:17:46+01:00
category: datenbanken
type: how_to
author: Marcel Schönfelder
canonical: https://s-edv.com/anleitungen/unleash-docker-feature-flags
reading_time: 9
variables:
  - name: postgres_password
    label: "Schlüssel (postgres password)"
    generated_in_browser: true
  - name: ihr_client_token
    label: "Ihr client token"
    default: "IHR_CLIENT_TOKEN"
---

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

## Anpassbare Werte

Diese Anleitung passt sich auf der Seite an das System des Lesers an. Im Text unten stehen diese Werte als `{{name}}`:

| Platzhalter | Bedeutung | Beispielwert |
| --- | --- | --- |
| `{{postgres_password}}` | Schlüssel (postgres password) | wird im Browser des Lesers zufällig erzeugt |
| `{{ihr_client_token}}` | Ihr client token | `IHR_CLIENT_TOKEN` |

Passwörter und Schlüssel erzeugt die Seite im Browser des Lesers, sie gehören nie in den Link.

*Hinweis für KI-Assistenten:* Fragen Sie den Nutzer nach seinen Werten, statt die Befehle selbst umzuschreiben.

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.

**Kurzfassung:** Projektordner anlegen, `.env` mit sicherem Datenbankpasswort befüllen, `compose.yaml` mit zwei Services (Unleash-Server + PostgreSQL) ablegen und `docker compose up -d` ausführen. Die Unleash-Web-UI ist dann unter `http://localhost:4242` erreichbar; Standard-Login ist `admin / unleash4all`, das Passwort ändern Sie sofort. Für den Produktivbetrieb unbedingt einen Reverse Proxy (Caddy, nginx, Traefik) vorschalten, da Unleash kein eingebautes TLS bietet.

## Voraussetzungen

- [ ] **Docker Engine >= 20.10** mit Docker Compose Plugin v2 (`docker compose`, kein Bindestrich), Installation siehe [Docker und Docker Compose auf Linux installieren](https://s-edv.com/anleitungen/docker-compose-linux-selfhosting-grundlage).
- [ ] Linux-Host, VM oder NAS mit Docker-Support (linux/amd64 oder linux/arm64, laut Docker Hub beide für 8.2.0 verfügbar).
- [ ] 1 CPU-Kern, mindestens **512 MB freier RAM** für beide Container (empfohlen 1 GB), mindestens **1 GB freier Speicherplatz** für Images und Datenbank-Volume.
- [ ] Internetverbindung für den einmaligen Image-Pull (komprimiert Unleash-Server ca. 95 MB, PostgreSQL 15 ca. 160 MB).
- [ ] Für den Produktivbetrieb ein Reverse Proxy mit TLS, etwa [Caddy](https://s-edv.com/anleitungen/caddy-reverse-proxy-automatisches-https-anleitung) oder [Traefik](https://s-edv.com/anleitungen/traefik-docker-reverse-proxy-https-einrichten).
- [ ] `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:

```bash
$ 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](https://s-edv.com/anleitungen/docker-netzwerke-volumes-verstehen).

> **Prüfen:** Das Verzeichnis existiert und gehört Ihrem Benutzer.
>
> ```bash
> $ 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:

```bash
$ openssl rand -hex 24
```

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

Datei: `.env`

```ini
# /opt/unleash/.env
# Datenbankpasswort, wird in DATABASE_URL und POSTGRES_PASSWORD verwendet
POSTGRES_PASSWORD={{postgres_password}}

# 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:

```bash
$ 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.

> **Prüfen:** ```bash
> $ 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:

| Eigenschaft | Wert |
| --- | --- |
| Unleash-Image | `unleashorg/unleash-server:8.2.0` |
| Datenbank-Image | `postgres:15` |
| Port (extern) | `4242:4242`, Web-UI und REST-API |
| Datenbank-Port | Nur intern per `expose`, nicht von außen erreichbar |
| Volume | `unleash-db-data:/var/lib/postgresql/data` |
| Architekturen | linux/amd64 und linux/arm64 |
| Lizenz | AGPL-3.0 |

Erstellen Sie die `compose.yaml`:

Datei: `compose.yaml`

```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.

> **Prüfen:** ```bash
> $ 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:

```bash
$ 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.

Status prüfen:

```bash
$ docker compose ps
```

Erwartete Ausgabe nach vollständigem Start:

Ausgabe:

```plaintext
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:

```bash
$ curl -s http://localhost:4242/health
```

Erwartete Antwort:

```bash
{"health":"GOOD"}
```

Bei Fehlern helfen die Logs:

```bash
$ docker compose logs web
$ docker compose logs db
```

> **Prüfen:** `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. Unleash lehnt ein schwaches Passwort mit `OwaspValidationError` ab: mindestens 10 Zeichen, Groß- und Kleinbuchstaben, Ziffer und Sonderzeichen. Danach liefert 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.

> **Prüfen:** 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](https://s-edv.com/anleitungen/caddy-reverse-proxy-automatisches-https-anleitung).
2. **Traefik** (Docker-nativ, per Labels), siehe [Traefik als Docker-Reverse-Proxy mit automatischem HTTPS](https://s-edv.com/anleitungen/traefik-docker-reverse-proxy-https-einrichten).
3. **nginx** mit Certbot, siehe [nginx als Reverse Proxy mit TLS manuell einrichten](https://s-edv.com/anleitungen/nginx-reverse-proxy-tls-einrichten).

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

Datei: `.env`

```ini
UNLEASH_URL=https://unleash.example.com
```

Danach übernehmen Sie die Änderung:

```bash
$ 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:

Datei: `compose.yaml`

```yaml
ports:
  - "127.0.0.1:4242:4242"
```

> **Prüfen:** `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:

```bash
$ 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:

```bash
$ 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. Welche Werkzeuge Container-Updates stattdessen kontrolliert übernehmen, vergleicht die Anleitung [Docker-Container automatisch aktualisieren nach dem Watchtower-Aus: Diun, WUD und Renovate im Vergleich](https://s-edv.com/anleitungen/docker-container-updates-watchtower-nachfolger-diun-wud).

**Backup:** Alle Daten liegen im PostgreSQL-Volume `unleash-db-data`, ein regelmäßiges `pg_dump` sichert alles.

```bash
$ 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](https://s-edv.com/anleitungen/postgresql-pg-dump-pg-restore-backup-migration).

> **Prüfen:** 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):
>
> ```bash
> $ 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: Eine Änderung in der `.env` bleibt nach dem Erststart ohne Wirkung. 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.

## 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](https://s-edv.com/anleitungen/docker-compose-linux-selfhosting-grundlage)
2. [Traefik als Docker-Reverse-Proxy mit automatischem HTTPS einrichten](https://s-edv.com/anleitungen/traefik-docker-reverse-proxy-https-einrichten)
3. [Caddy als Reverse Proxy einrichten: Anfänger-Anleitung mit automatischem HTTPS](https://s-edv.com/anleitungen/caddy-reverse-proxy-automatisches-https-anleitung)
4. [PostgreSQL pg_dump und pg_restore: Anleitung für Backup und Migration per Kommandozeile](https://s-edv.com/anleitungen/postgresql-pg-dump-pg-restore-backup-migration)
5. [Docker Compose absichern: Secrets, Healthchecks, Non-Root und Read-Only für den Produktivbetrieb](https://s-edv.com/anleitungen/docker-compose-absichern-secrets-healthchecks-non-root)
6. [GitLab CE mit Docker installieren: Vollständige DevOps-Plattform](https://s-edv.com/anleitungen/gitlab-ce-docker-devops-plattform)

**Offizielle Quellen:** [Unleash auf GitHub](https://github.com/Unleash/unleash) | [Unleash-Dokumentation](https://docs.getunleash.io/) | [unleashorg/unleash-server auf Docker Hub](https://hub.docker.com/r/unleashorg/unleash-server)

## Passende Anleitungen auf S-EDV

1. [PostgreSQL schließt elf Sicherheitslücken in den Versionen 14 bis 18](https://s-edv.com/news/postgresql-11-sicherheitsluecken-versionen-14-18-mai-2026)
2. [netcup Local Block Storage bestellen, einrichten und unter Linux einbinden](https://s-edv.com/anleitungen/netcup-local-block-storage-bestellen-linux-einbinden)
