Valkey mit Docker installieren: BSD-lizenzierter Community-Fork als Redis-Ersatz

Redis steht seit Version 7.4 (2024) nicht mehr unter der BSD-Lizenz, sondern unter RSALv2/SSPLv1, ab Redis 8 zusätzlich wahlweise unter AGPLv3. Valkey ist der Fork des letzten BSD-lizenzierten Stands (Redis 7.2.4), wird unter dem Dach der Linux Foundation entwickelt und steht unter der BSD-3-Clause-Lizenz. Valkey spricht dasselbe Protokoll wie Redis 7.2; redis-py, ioredis, Jedis oder phpredis verbinden sich ohne Code-Änderung. Diese Anleitung richtet Valkey 9.1 mit Docker Compose auf einem Linux-Host ein, sichert es mit Passwort und Speicherlimit ab und konfiguriert Persistenz und Backup.

Voraussetzungen

• Docker Engine ab Version 24 und Docker Compose Plugin v2 (docker compose version). Die Einrichtung beschreibt Docker und Docker Compose auf Linux installieren.
• Linux-Host, VM oder NAS mit Docker, amd64 oder arm64
• Freier RAM mindestens in Höhe des geplanten maxmemory plus etwa 50 %, da AOF-Rewrite und RDB-Snapshot per Fork zusätzlichen Speicher belegen (bei 512 MB Limit also rund 800 MB)
• SSD-Speicher für das Daten-Volume, wenn AOF aktiv ist

Eckdaten im Überblick

Schritt 1: Projektordner anlegen

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

Zielstruktur:

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

Schritt 2: .env-Datei mit Passwort anlegen

Das Passwort steht nur an einer Stelle, in der .env. Compose übergibt es beim Start an Valkey und an valkey-cli. So kann es nicht zwischen zwei Dateien auseinanderlaufen.

$ cd /opt/valkey
$ echo "VALKEY_PASSWORD=$(openssl rand -hex 32)" | sudo tee .env > /dev/null
$ sudo chmod 600 .env

Das erzeugte Passwort besteht aus 64 Hex-Zeichen und enthält keine Sonderzeichen, die in YAML oder in der Shell Probleme bereiten.

Schritt 3: valkey.conf erstellen

Die Datei steuert Netzwerk, Persistenz und Speicherlimit.

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

# Im Container auf allen Schnittstellen lauschen. Von außen erreichbar
# ist nur, was compose.yaml freigibt (hier: 127.0.0.1:6379).
bind * -::*
protected-mode yes
tcp-keepalive 300

# Persistenz: RDB-Snapshots plus AOF
save 3600 1 300 100 60 10000
appendonly yes
appendfsync everysec

# Speicherlimit gegen OOM-Kills
maxmemory 512mb
maxmemory-policy allkeys-lru

loglevel notice

allkeys-lru verdrängt bei vollem Speicher beliebige Schlüssel und passt für reine Caches. Nutzen Sie Valkey als Datenspeicher oder Queue, setzen Sie noeviction; Schreibbefehle scheitern dann bei vollem Speicher mit einem Fehler, statt Daten still zu löschen.

Schritt 4: compose.yaml erstellen

Der Port ist an 127.0.0.1 gebunden und damit nur vom Host erreichbar. --requirepass setzt das Passwort aus der .env; VALKEYCLI_AUTH übergibt es an valkey-cli im Container, sodass Healthcheck und Ihre Befehle ohne -a auskommen.

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

volumes:
  valkey-data:

networks:
  valkey-net:

Verwenden Sie einen festen Tag wie 9.1.2-alpine statt latest, damit ein Versionswechsel nur geplant stattfindet. Das Passwort ist für Benutzer mit Zugriff auf den Docker-Socket über docker inspect lesbar; dieser Zugriff entspricht ohnehin root-Rechten auf dem Host.

Schritt 5: Valkey starten und prüfen

$ cd /opt/valkey
$ docker compose up -d
$ docker compose ps

Erwartete Ausgabe nach etwa 20 Sekunden:

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

docker compose logs valkey zeigt Ready to accept connections tcp. Meldungen wie Can't open the append-only file oder Permission denied deuten auf Rechteprobleme am Volume hin (siehe Fehlerbehebung).

$ docker compose exec valkey valkey-cli ping
$ docker compose exec valkey valkey-cli INFO server | grep -E "valkey_version|redis_version"

Erwartet: PONG, dann valkey_version:9.1.2 und redis_version:7.2.4 (Kompatibilitätsstand). Ein Aufruf ohne Passwort muss scheitern: docker compose exec valkey sh -c 'unset VALKEYCLI_AUTH; valkey-cli ping' liefert NOAUTH Authentication required.

Schritt 6: Persistenz mit einem Test-Key prüfen

$ docker compose exec valkey valkey-cli SET testkey "s-edv.com"
$ docker compose restart valkey
$ docker compose exec valkey valkey-cli GET testkey

Erwartet: OK und nach dem Neustart "s-edv.com". Fehlt der Wert, ist das Volume nicht eingebunden oder appendonly yes fehlt.

Schritt 7: Migration von Redis (optional)

Direkt migrieren lassen sich Redis-Installationen bis Version 7.2. Deren RDB-Dateien (Format 11) und AOF lädt Valkey unverändert. Redis 7.4 und 8.x schreiben RDB-Formate ab Version 12, die Valkey als fremd einstuft und nicht lädt. Prüfen Sie deshalb zuerst die Version:

$ docker compose exec redis redis-cli INFO server | grep redis_version

Bei Redis bis 7.2: Sichern Sie das Datenverzeichnis, stoppen Sie Redis und ändern Sie in der bestehenden compose.yaml das Image:

# Vorher:
image: redis:7.2-alpine

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

Das Volume /data bleibt gleich. Den Pfad der Konfigurationsdatei im Volume-Mount und im command übernehmen Sie wie in Schritt 4; redis.conf-Direktiven versteht Valkey weiterhin. Bei Redis 7.4 oder 8.x befüllen Sie Valkey neu: Caches baut die Anwendung selbst wieder auf, dauerhafte Daten übertragen Sie auf Schlüsselebene mit einem Migrationswerkzeug.

Valkey 9 speichert im neuen RDB-Format 80, das Redis nicht lesen kann. Ein Rückweg zu Redis ist deshalb nur über die vorher erstellte Sicherung möglich.

Schritt 8: Update und Backup

Für ein Backup lösen Sie zuerst einen Snapshot aus und sichern dann das Volume (Volume-Name = Projektordner plus Volume, hier valkey_valkey-data):

cd /opt/valkey
docker compose exec valkey valkey-cli BGSAVE
sudo mkdir -p /backup
docker run --rm \
  -v valkey_valkey-data:/data:ro \
  -v /backup:/backup \
  alpine:3.24 tar czf /backup/valkey-$(date +%Y%m%d).tar.gz -C /data .

Für automatische Sicherungen außer Haus siehe 3-2-1-Backup-Strategie mit Restic und S3.

Für ein Update erstellen Sie zuerst ein Backup, lesen die Release Notes auf GitHub und tragen dann den neuen Tag in compose.yaml ein, z. B. 9.1.3-alpine:

$ docker compose pull
$ docker compose up -d

Ohne geänderten Tag lädt pull nichts Neues.

Typische Fehler und Lösungen

Container bleibt „unhealthy“, Log zeigt NOAUTH

Der Eintrag VALKEYCLI_AUTH fehlt in compose.yaml, oder die .env wurde nach dem Start geändert. Prüfen Sie compose.yaml und führen Sie docker compose up -d --force-recreate aus.

„Permission denied“ beim Schreiben in /data

Das Entrypoint-Skript übergibt /data beim Start automatisch an den Benutzer valkey, jedoch nur, wenn der Container als root startet. Mit user: in compose.yaml oder einem Bind-Mount auf NFS muss das Verzeichnis vorher der verwendeten UID gehören.

Container startet nicht, Log zeigt Fatal error, can't open config file

Der Pfad im command stimmt nicht mit dem Mount überein, oder die Datei fehlte beim ersten Start und Docker hat an ihrer Stelle ein Verzeichnis angelegt. Löschen Sie dieses Verzeichnis, legen Sie die Datei an und starten Sie neu.

OOM-Kill des Containers

maxmemory fehlt oder liegt zu nah am verfügbaren RAM. Setzen Sie ein Limit mit Reserve für Fork-Vorgänge (siehe Voraussetzungen).

Port 6379 von außen erreichbar

Das Port-Mapping lautet 6379:6379 statt 127.0.0.1:6379:6379. Docker umgeht dabei ufw-Regeln. Korrigieren Sie das Mapping und führen Sie docker compose up -d aus.

Langsame Schreibvorgänge mit AOF

appendfsync always auf HDD oder NFS. Mit everysec verlieren Sie bei einem Absturz höchstens etwa eine Sekunde Schreibvorgänge.

Anleitungen für bitnami/valkey

Dieses Image nutzt andere Variablen (VALKEY_PASSWORD) und Pfade (/bitnami/valkey). Konfigurationen sind nicht übertragbar; diese Anleitung gilt für das offizielle Image valkey/valkey.

Häufige Fragen

Ist Valkey ein vollständiger Redis-Ersatz?

Für Anwendungen, die Redis bis 7.2 nutzen, ja: Protokoll und Befehle sind kompatibel. Neuere, nur in Redis 7.4 oder 8 eingeführte Befehle und Module (etwa die in Redis 8 integrierten Datentypen) sind nicht automatisch vorhanden. Prüfen Sie diese vor dem Umstieg.

Welches Image-Tag sollten Sie in Produktion verwenden?

Einen vollständigen Versions-Tag wie 9.1.2-alpine oder 9.1.2-trixie (Debian, wenn Sie im Container weitere Pakete benötigen). Tags wie 9.1-alpine ziehen Patch-Updates automatisch nach, latest auch Hauptversionen.

Wie unterscheiden sich RDB und AOF?

RDB schreibt periodische Snapshots: schneller Neustart, aber Verlust der Änderungen seit dem letzten Snapshot. AOF protokolliert jeden Schreibbefehl: bei everysec höchstens etwa eine Sekunde Verlust, dafür größere Dateien. Die Kombination beider ist der übliche Produktionsstandard.

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

Hängen Sie den Anwendungscontainer an das Netzwerk valkey_valkey-net (in dessen compose.yaml als external: true deklariert). Als Host tragen Sie valkey, Port 6379 und das Passwort ein. phpredis und ioredis funktionieren ohne Anpassung. Für Sessions eignet sich noeviction oder volatile-lru besser als allkeys-lru, damit aktive Sitzungen nicht verdrängt werden.

Was passiert, wenn Sie maxmemory nicht setzen?

Valkey wächst dann bis an die RAM-Grenze des Hosts, und der Linux-OOM-Killer beendet Valkey oder andere Prozesse. Setzen Sie immer ein Limit.

Wie überwachen Sie Valkey im Betrieb?

valkey-cli INFO liefert Speicher, Verbindungen, Persistenz und Replikation. Für Prometheus nutzen Sie den Redis-Exporter, der auch mit Valkey funktioniert; den Monitoring-Stack beschreibt cAdvisor mit Prometheus: Docker-Container-Metriken sammeln.

Fazit

Valkey ersetzt Redis bis Version 7.2 ohne Änderungen an der Anwendung und steht unter BSD-Lizenz. Für den Dauerbetrieb entscheidend sind ein Passwort, ein maxmemory-Limit, ein persistentes Volume, der an 127.0.0.1 gebundene Port und ein fester Image-Tag. Wie Sie Compose-Stacks zusätzlich härten, zeigt Docker Compose absichern: Secrets, Healthchecks, Non-Root und Read-Only.

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