Valkey mit Docker installieren: Community-Fork als lizenzfreier Redis-Ersatz

Seit Redis 2024 auf eine proprietäre SSPL-Lizenz gewechselt ist, suchen viele KMU und Entwickler nach einem rechtssicheren Ersatz. Valkey ist genau das: ein von der Linux Foundation geführter Community-Fork unter der bewährten BSD-3-Clause-Lizenz – kein Lizenzanwalt nötig, kein Vendor-Lock-in. Das Projekt zählt über 26.000 GitHub-Stars, veröffentlichte im Mai 2026 Version 9.1.0 und unterstützt dieselben Datenstrukturen, dasselbe Protokoll und dieselben Clients wie Redis. Bestehende redis-py-, ioredis- oder Jedis-Anwendungen funktionieren ohne eine einzige Code-Änderung. Diese Anleitung zeigt dir, wie du Valkey mit Docker Compose plattformneutral auf einem Linux-Host (Ubuntu, Debian, VM oder NAS mit Docker) aufsetzte, absicherst und für den Dauerbetrieb konfigurierst.

Voraussetzungen

1. Docker Engine 24+ und Docker Compose Plugin v2 (Befehl: docker compose ohne Bindestrich) – wie du beides installierst, erklärt die Anleitung Docker und Docker Compose auf Linux installieren.
2. Linux-Host, VM oder NAS mit Docker-Unterstützung (amd64 oder arm64)
3. Mindestens 512 MB freier RAM; für Produktion 1 GB+ empfohlen
4. Persistenter Speicher für das Daten-Volume – SSD für AOF-Betrieb empfohlen
5. Internetzugang zu Docker Hub für den ersten Image-Pull
6. Texteditor für .env und valkey.conf

Valkey im Überblick: Eckdaten auf einen Blick

Schritt 1: Projektordner und Verzeichnisstruktur anlegen

Alle projektbezogenen Dateien kommen in einen gemeinsamen Ordner. Das hält das Setup übersichtlich und ermöglicht saubere Backups.

mkdir -p /opt/valkey/valkey-config
cd /opt/valkey

Die spätere Ordnerstruktur sieht so aus:

/opt/valkey/
├── compose.yaml
├── .env
└── valkey-config/
    └── valkey.conf

Verifizieren: ls -la /opt/valkey/ zeigt den Ordner valkey-config/. Ohne diesen Schritt schlägt der Volume-Mount der Konfigurationsdatei beim späteren Start fehl.

Schritt 2: .env-Datei mit Passwort anlegen

Secrets gehören nie direkt in die compose.yaml. Die .env-Datei im Projektordner wird von Docker Compose automatisch eingelesen und hält das Passwort aus der Versionskontrolle heraus.

# /opt/valkey/.env
VALKEY_PASSWORD=dein-langes-sicheres-passwort-hier

Wähle ein starkes Passwort (mindestens 20 zufällige Zeichen). Ohne requirepass ist Valkey im Docker-Netzwerk für jeden Container erreichbar – auch ohne exponierten Port ein Risiko in gemeinsam genutzten Umgebungen.

Schütze die Datei anschließend vor unberechtigtem Lesen:

chmod 600 /opt/valkey/.env

Verifizieren: cat /opt/valkey/.env zeigt dein Passwort. ls -la /opt/valkey/.env zeigt die Berechtigungen -rw-------.

Schritt 3: valkey.conf erstellen

Die Konfigurationsdatei steuert Persistenz, Speicherlimit und Sicherheit. Valkey erwartet sie im Container unter /usr/local/etc/valkey/valkey.conf – nicht unter /etc/valkey/valkey.conf wie bei einer Bare-Metal-Installation. Ein falscher Pfad führt dazu, dass Valkey die Datei stillschweigend ignoriert.

# /opt/valkey/valkey-config/valkey.conf

# Authentifizierung
requirepass dein-langes-sicheres-passwort-hier

# Netzwerk
bind 0.0.0.0
tcp-keepalive 30

# Persistenz: RDB + AOF kombinieren fuer maximale Datensicherheit
# RDB-Snapshots: nach 3600s bei 1 Änderung, 300s bei 100, 60s bei 10000
save 3600 1 300 100 60 10000
appendonly yes
appendfsync everysec

# Speicherlimit (OOM-Schutz – ohne diesen Wert kann Valkey den
# gesamten Host-RAM belegen und einen OOM-Kill ausloesen)
maxmemory 512mb
maxmemory-policy allkeys-lru

# Logging
loglevel notice

Das Passwort in der valkey.conf muss mit dem Wert in der .env-Datei übereinstimmen, da der Healthcheck in der compose.yaml die Variable ${VALKEY_PASSWORD} nutzt. Trage hier denselben Wert ein, den du in Schritt 2 gesetzt hast.

Verifizieren: cat /opt/valkey/valkey-config/valkey.conf zeigt alle gesetzten Parameter. Prüfe insbesondere, dass requirepass und das VALKEY_PASSWORD aus der .env identisch sind – ein Mismatch lässt den Healthcheck später auf „unhealthy" schalten.

Schritt 4: compose.yaml erstellen

Die compose.yaml ist das Herzstück des Setups. Wichtige Designentscheidungen im Überblick: Der Port ist bewusst an 127.0.0.1 gebunden, damit er nicht direkt aus dem Internet erreichbar ist. Das Named Volume valkey-data sichert die Daten über Container-Neustarts hinaus. Der Healthcheck nutzt valkey-cli -a mit dem Passwort aus der .env, damit Docker den Container korrekt als „healthy" markiert.

# /opt/valkey/compose.yaml
services:
  valkey:
    image: valkey/valkey:9.1-alpine
    container_name: valkey
    restart: unless-stopped
    ports:
      - "127.0.0.1:6379:6379"
    volumes:
      - valkey-data:/data
      - ./valkey-config/valkey.conf:/usr/local/etc/valkey/valkey.conf:ro
    command: valkey-server /usr/local/etc/valkey/valkey.conf
    environment:
      - VALKEY_EXTRA_FLAGS=--loglevel notice
    healthcheck:
      test: ["CMD", "valkey-cli", "-a", "${VALKEY_PASSWORD}", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 10s
    networks:
      - valkey-net

volumes:
  valkey-data:
    driver: local

networks:
  valkey-net:
    driver: bridge

Verwende in Produktion stets einen festen Tag wie 9.1-alpine statt :latest – unkontrollierte Updates können Breaking Changes einbringen. Die Alpine-Variante ist mit rund 5 MB Basis-Image schlanker; wechsle zu valkey/valkey:9.1 (Debian), falls du zusätzliche Systempakete im Container benötigst.

Verifizieren: docker compose config im Verzeichnis /opt/valkey/ validiert die Syntax und zeigt die aufgelöste Konfiguration inklusive der Umgebungsvariablen aus der .env. Erscheint dabei VALKEY_PASSWORD mit dem korrekten Wert, ist die Datei fehlerfrei.

Schritt 5: Valkey starten und prüfen

Starte den Stack im Hintergrund:

cd /opt/valkey
docker compose up -d

Beim ersten Start lädt Docker das Image herunter (ca. 10–20 MB für die Alpine-Variante). Prüfe danach den Container-Status:

docker compose ps

Erwartete Ausgabe nach ca. 30 Sekunden (Healthcheck benötigt start_period: 10s + bis zu 5 Versuche):

NAME      IMAGE                        COMMAND                  SERVICE   STATUS              PORTS
valkey    valkey/valkey:9.1-alpine     "docker-entrypoint.s…"   valkey    Up 30 seconds (healthy)   127.0.0.1:6379->6379/tcp

Prüfe die Logs auf Fehler:

docker compose logs valkey

Im Log solltest du sehen, dass Valkey die Konfigurationsdatei lädt, den Port 6379 abhört und – falls bereits ein RDB-Snapshot vorhanden ist – diesen einliest. Fehlermeldungen wie Can't open the append-only file oder Permission denied deuten auf Volume-Berechtigungsprobleme hin.

Verifizieren: Führe ein direktes Ping über den CLI aus:

docker compose exec valkey valkey-cli -a "${VALKEY_PASSWORD}" ping

Erwartete Antwort: PONG. Für die Server-Details:

docker compose exec valkey valkey-cli -a "${VALKEY_PASSWORD}" INFO server

Die Ausgabe enthält u. a. redis_version:7.2.x (Protokoll-Kompatibilitätsversion) und valkey_version:9.1.0. Das bestätigt: Valkey läuft, antwortet über das Redis-Protokoll und ist einsatzbereit.

Schritt 6: Funktion mit einem Test-Key bestätigen

Schreibe einen Schlüssel und lies ihn direkt wieder aus – der schnellste Smoke-Test für Cache und Persistenz:

docker compose exec valkey valkey-cli -a "${VALKEY_PASSWORD}" SET testkey "s-edv.com"
docker compose exec valkey valkey-cli -a "${VALKEY_PASSWORD}" GET testkey

Erwartete Ausgabe:

OK
"s-edv.com"

Teste anschließend die Persistenz: Starte den Container neu und prüfe, ob der Schlüssel noch vorhanden ist.

docker compose restart valkey
docker compose exec valkey valkey-cli -a "${VALKEY_PASSWORD}" GET testkey

Antwort muss wieder "s-edv.com" sein – andernfalls ist das Volume nicht korrekt eingebunden oder appendonly yes fehlt in der Konfiguration.

Verifizieren: docker compose exec valkey valkey-cli -a "${VALKEY_PASSWORD}" INFO persistence zeigt aof_enabled:1 und rdb_last_bgsave_status:ok. Beide Werte bestätigen, dass RDB und AOF aktiv sind.

Schritt 7: Migration von Redis (optional)

Wechselst du von einem bestehenden Redis-Deployment zu Valkey, ist der Aufwand minimal: Valkey ist vollständig Drop-in-kompatibel zu Redis 7.2. Alle gängigen Clients – redis-py, ioredis, Jedis, Lettuce – funktionieren ohne Code-Änderungen, weil das zugrunde liegende RESP-Protokoll identisch ist. Im Container sind redis-server und redis-cli als Symlinks auf die Valkey-Binärdateien vorhanden.

Ändere in deiner bestehenden compose.yaml nur das Image:

# Vorher:
image: redis:7.2-alpine

# Nachher:
image: valkey/valkey:9.1-alpine

Beachte dabei: Das offizielle Valkey-Image erwartet die Konfigurationsdatei unter /usr/local/etc/valkey/valkey.conf, nicht unter /etc/redis/redis.conf. Passe den Volume-Mount und den command-Eintrag entsprechend an.

Starte danach den Stack neu:

docker compose up -d

Verifizieren: docker compose ps zeigt Status „healthy". docker compose exec valkey valkey-cli -a "${VALKEY_PASSWORD}" INFO server enthält valkey_version:9.1.0 – die Migration ist abgeschlossen.

Schritt 8: Update und Backup

Ein Update auf eine neue Valkey-Version ist mit zwei Befehlen erledigt:

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

Docker lädt das neue Image, stoppt den alten Container und startet den neuen – dank restart: unless-stopped und dem benannten Volume gehen dabei keine Daten verloren. Für ein Backup des Daten-Verzeichnisses genügt ein Snapshot des Named Volumes oder ein Tar-Archiv:

# Einmalige Sicherung des Volumes
docker run --rm \
  -v valkey_valkey-data:/data \
  -v /backup:/backup \
  alpine tar czf /backup/valkey-backup-$(date +%Y%m%d).tar.gz -C /data .

Für eine automatisierte Backup-Strategie empfiehlt sich die Anleitung 3-2-1-Backup-Strategie mit Restic und S3.

Verifizieren: docker compose ps zeigt nach dem Update die neue Image-Version und Status „healthy". ls -lh /backup/ bestätigt das erstellte Archiv.

Troubleshooting / Typische Fehler

1. Container startet, bleibt aber „unhealthy": Der Healthcheck schlägt fehl, weil valkey-cli ping ohne Passwort ausgeführt wird. Ursache: VALKEY_PASSWORD in der .env stimmt nicht mit requirepass in der valkey.conf überein. Lösung: beide Werte angleichen, dann docker compose up -d --force-recreate.
2. „Permission denied" beim Schreiben in /data: Das Volume-Verzeichnis gehört root, der Container-Prozess läuft jedoch als unprivilegierter User. Lösung: docker compose exec valkey chown -R valkey:valkey /data oder Named Volume statt Bind-Mount verwenden.
3. Konfigurationsdatei wird ignoriert: Falscher Pfad im Volume-Mount oder fehlender command-Eintrag. Valkey startet ohne Config, wenn der Pfad nicht stimmt – ohne Fehlermeldung. Lösung: Pfad im Mount auf /usr/local/etc/valkey/valkey.conf prüfen; command: valkey-server /usr/local/etc/valkey/valkey.conf muss in der compose.yaml stehen.
4. OOM-Kill des Containers: maxmemory fehlt in der Konfiguration. Valkey belegt dann beliebig viel Host-RAM. Lösung: maxmemory 512mb (oder angemessener Wert) und maxmemory-policy allkeys-lru in der valkey.conf setzen.
5. Port 6379 von außen erreichbar: Der Port ist in der compose.yaml als 0.0.0.0:6379:6379 gebunden statt auf 127.0.0.1. Lösung: Port-Mapping auf 127.0.0.1:6379:6379 ändern und docker compose up -d erneut ausführen.
6. Performance-Einbrüche mit AOF: appendfsync always auf HDD oder NFS ist sehr langsam. Lösung: auf appendfsync everysec wechseln – minimaler Datenverlust (maximal 1 Sekunde) bei deutlich besserem Durchsatz.
7. Bitnami-Image-Verwechslung: bitnami/valkey verwendet andere Umgebungsvariablen (VALKEY_PASSWORD statt VALKEY_EXTRA_FLAGS) und andere Volume-Pfade (/bitnami/valkey statt /data). Konfigurationen sind nicht portierbar. Diese Anleitung gilt ausschließlich für das offizielle Image valkey/valkey.

Häufige Fragen

Ist Valkey ein vollständiger Redis-Ersatz?

Ja. Valkey ist vollständig API- und Protokoll-kompatibel zu Redis 7.2. Alle gängigen Clients (redis-py, ioredis, Jedis, Lettuce, valkey-go) funktionieren ohne Code-Änderungen, da das RESP-Protokoll identisch ist. Im Container verweisen die Symlinks redis-server und redis-cli auf die Valkey-Binärdateien.

Welches Image-Tag sollte ich in Produktion verwenden?

Verwende valkey/valkey:9.1-alpine für minimalen Footprint oder valkey/valkey:9.1 (Debian) für maximale Pakete-Kompatibilität. Vermeide :latest in Produktion – unkontrollierte Major-Version-Updates können Breaking Changes einbringen. Für Long-Term-Support-Anforderungen gibt es zusätzlich den 8.x-Branch.

Wie unterscheiden sich RDB und AOF?

RDB erstellt periodische Komplett-Snapshots (schnelles Recovery, möglicher Datenverlust von Minuten bis Stunden bei einem Absturz zwischen zwei Snapshots). AOF loggt jeden einzelnen Schreibbefehl (minimaler Datenverlust von maximal einer Sekunde bei appendfsync everysec, dafür größere Dateien). Für Produktion empfiehlt sich die Kombination beider Methoden: appendonly yes zusammen mit den save-Parametern in der valkey.conf.

Wie setze ich Valkey als Session-Cache für eine PHP- oder Node.js-Anwendung ein?

Verbinde die Anwendung über das valkey-net-Netzwerk mit dem Valkey-Container. In der Anwendungskonfiguration trägst du als Host valkey (Container-Name), Port 6379 und das Passwort ein. Da Valkey das Redis-Protokoll spricht, funktionieren PHP-Erweiterungen wie phpredis oder Node.js-Pakete wie ioredis ohne Anpassung.

Was passiert, wenn ich maxmemory nicht setze?

Ohne maxmemory-Limit kann Valkey den gesamten verfügbaren Host-RAM belegen. Der Linux-OOM-Killer beendet dann den Prozess – entweder Valkey selbst oder andere kritische Prozesse auf dem Host. Setze deshalb immer ein sinnvolles Limit und wähle eine passende maxmemory-policy (empfohlen: allkeys-lru für Cache-Szenarien, noeviction wenn kein Datenverlust akzeptabel ist).

Wie überwache ich Valkey im Betrieb?

Der eingebaute INFO-Befehl liefert alle relevanten Metriken: INFO all zeigt Speicherverbrauch, Verbindungen, Replikationsstatus und Persistenz-Infos. Für kontinuierliches Monitoring lässt sich Valkey über den Redis-Exporter in Prometheus integrieren – passend dazu erklärt die Anleitung cAdvisor mit Prometheus: Docker-Container-Metriken sammeln den vollständigen Stack.

Fazit

Valkey ist mehr als ein Notfall-Ersatz für Redis: Es ist ein aktiv gepflegtes Open-Source-Projekt mit klarer Governance unter der Linux Foundation, das du ohne Lizenzsorgen in KMU-Produktion einsetzen kannst. Die Vollkompatibilität zum Redis-Protokoll macht den Umstieg zum Nicht-Event – bestehende Anwendungen, Clients und Konfigurationsdateien laufen weiter. Kritisch für den stabilen Betrieb sind drei Punkte: erstens ein Passwort via requirepass, zweitens ein maxmemory-Limit gegen OOM-Kills und drittens ein persistentes Named Volume für /data. Wer diese drei Stellschrauben richtig setzt, hat einen produktionsreifen In-Memory-Key-Value-Store in unter 15 Minuten aufgesetzt.

Für den Einstieg in das Docker-Compose-Ökosystem empfiehlt sich ergänzend die Anleitung Docker Compose absichern: Secrets, Healthchecks, Non-Root und Read-Only für den Produktivbetrieb.

Weiterführende Anleitungen und Quellen

1. Docker und Docker Compose auf Linux installieren (Ubuntu/Debian): die Self-Hosting-Grundlage
2. Docker Compose absichern: Secrets, Healthchecks, Non-Root und Read-Only für den Produktivbetrieb
3. cAdvisor mit Prometheus: Docker-Container-Metriken sammeln und in Grafana visualisieren
4. 3-2-1-Backup-Strategie umsetzen: Anleitung mit Restic, USB-Disk und S3-Cloud

Offizielle Quellen: Valkey auf Docker Hub · Valkey GitHub Repository · Valkey-Dokumentation: Persistenz · Valkey-Dokumentation: Sicherheit