--- title: "Valkey mit Docker installieren: BSD-lizenzierter Community-Fork als Redis-Ersatz" date: 2026-08-12T21:57:22+02:00 modified: 2026-11-08T15:05:35+01:00 category: datenbanken type: how_to author: Marcel Schönfelder canonical: https://s-edv.com/anleitungen/valkey-docker-redis-alternative reading_time: 8 --- # 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. **Kurzfassung:** Legen Sie `/opt/valkey` mit `.env` (Passwort), `valkey.conf` (Persistenz, Speicherlimit) und `compose.yaml` an. Das Image `valkey/valkey:9.1.2-alpine` läuft mit an `127.0.0.1` gebundenem Port 6379 und Healthcheck. Nach `docker compose up -d` prüfen Sie mit `docker compose exec valkey valkey-cli ping` auf `PONG`. Ein Umstieg von Redis gelingt direkt nur von Redis bis 7.2; Datenbestände aus Redis 7.4 oder 8 kann Valkey nicht laden. ## Voraussetzungen - [ ] **Docker Engine** ab Version 24 und **Docker Compose Plugin** v2 (`docker compose version`). Die Einrichtung beschreibt [Docker und Docker Compose auf Linux installieren](https://s-edv.com/anleitungen/docker-compose-linux-selfhosting-grundlage). - [ ] 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 | Parameter | Wert | | --- | --- | | Image (Alpine) | `valkey/valkey:9.1.2-alpine` (Alpine 3.24) | | Image (Debian) | `valkey/valkey:9.1.2-trixie` | | Aktuelle Version | 9.1.2 vom 01.09.2026; 9.2 ist Release Candidate | | Weiter gepflegte Zweige | 9.0.x, 8.1.x, 8.0.x | | Lizenz | BSD-3-Clause | | Port | 6379 (Clients, Replikation); 16379 Cluster-Bus; 26379 Sentinel | | Daten im Container | `/data` (RDB-Snapshots, AOF) | | Konfigurationsdatei | frei wählbar, hier `/usr/local/etc/valkey/valkey.conf` | | Redis-Kompatibilität | Protokoll Redis 7.2.4; `redis-cli` und `redis-server` als Symlinks | ## Schritt 1: Projektordner anlegen ```bash $ sudo mkdir -p /opt/valkey/valkey-config $ cd /opt/valkey ``` Zielstruktur: ```bash /opt/valkey/ ├── compose.yaml ├── .env └── valkey-config/ └── valkey.conf ``` > **Prüfen:** `ls -la /opt/valkey/` zeigt den Ordner `valkey-config/`. ## 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. ```bash $ 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. > **Prüfen:** `ls -la /opt/valkey/.env` zeigt `-rw-------`, `sudo cat /opt/valkey/.env` eine Zeile `VALKEY_PASSWORD=…`. ## Schritt 3: valkey.conf erstellen Die Datei steuert Netzwerk, Persistenz und Speicherlimit. ```ini # /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. > **Prüfen:** `grep -E "^(maxmemory|appendonly|bind)" valkey-config/valkey.conf` zeigt die drei gesetzten Parameter. ## 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. ```yaml # /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. > **Prüfen:** `docker compose config` gibt die Konfiguration ohne Fehler aus; im `command` steht nach `--requirepass` Ihr Passwort. ## Schritt 5: Valkey starten und prüfen ```bash $ cd /opt/valkey $ docker compose up -d $ docker compose ps ``` Erwartete Ausgabe nach etwa 20 Sekunden: Ausgabe: ```plaintext 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). > **Prüfen:** ```bash > $ 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 ```bash $ 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. > **Prüfen:** `docker compose exec valkey valkey-cli INFO persistence` zeigt `aof_enabled:1` und `rdb_last_bgsave_status:ok`. Entfernen Sie den Test-Key anschließend mit `valkey-cli DEL testkey`. ## 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: ```bash $ 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: Datei: `compose.yaml` ```yaml # 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. > **Prüfen:** `docker compose ps` zeigt „healthy“, `valkey-cli DBSIZE` dieselbe Schlüsselanzahl wie vorher unter Redis. ## 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`): ```bash 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](https://s-edv.com/anleitungen/3-2-1-backup-strategie-praktisch-umsetzen). 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`: ```bash $ docker compose pull $ docker compose up -d ``` Ohne geänderten Tag lädt `pull` nichts Neues. > **Prüfen:** `ls -lh /backup/` zeigt das Archiv mit plausibler Größe; nach dem Update meldet `valkey-cli INFO server` die neue `valkey_version` und `docker compose ps` „healthy“. ## 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](https://s-edv.com/anleitungen/linux-server-absichern-ufw-fail2ban). 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](https://s-edv.com/anleitungen/cadvisor-prometheus-docker-container-metriken). ## 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](https://s-edv.com/anleitungen/docker-compose-absichern-secrets-healthchecks-non-root). ## 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. [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) 3. [cAdvisor mit Prometheus: Docker-Container-Metriken sammeln und in Grafana visualisieren](https://s-edv.com/anleitungen/cadvisor-prometheus-docker-container-metriken) 4. [3-2-1-Backup-Strategie umsetzen: Anleitung mit Restic, USB-Disk und S3-Cloud](https://s-edv.com/anleitungen/3-2-1-backup-strategie-praktisch-umsetzen) Offizielle Quellen: [Valkey auf Docker Hub](https://hub.docker.com/r/valkey/valkey/) · [Valkey GitHub Repository](https://github.com/valkey-io/valkey) · [Valkey-Dokumentation: Persistenz](https://valkey.io/topics/persistence/) · [Valkey-Dokumentation: Sicherheit](https://valkey.io/topics/security/)