Add podman compose fallback. (#430)

Author: ArgusLi

docs-site/src/content/docs/development/contributing.md

@@ -123,6 +123,8 @@ For the full-featured desktop application:
 3. **Start dev servers:** `npm run dev` or use `./quickstart-web.sh`
 4. **Connect:** Open http://localhost:5173 and manually add connection to `localhost:7001`
 
+> These scripts use Docker when its daemon is running and fall back to Podman otherwise. Force a choice with `CONTAINER_ENGINE=docker` or `CONTAINER_ENGINE=podman`. See `tools/README.md` for Podman requirements.
+
 ### Windows/WSL Users
 
 Fix line endings before running scripts:
@@ -139,6 +141,8 @@ cd tools/valkey-cluster
 docker compose down -v
 ```
 
+(or `podman compose down -v` if the scripts selected Podman)
+
 ## IDE Setup
 
 ### VSCode

quickstart-web.sh

@@ -33,8 +33,8 @@ echo "📝 The application will open at http://localhost:5173"
 echo "🔌 Auto-connection to local cluster is configured"
 echo ""
 echo "💡 Cluster is running in the background"
-echo "   - Use 'docker logs valkey-cluster-valkey-7001-1' to see cluster logs"
-echo "   - Use 'docker compose -f tools/valkey-cluster/docker-compose.yml down -v' to stop cluster"
+echo "   - Use '$COMPOSE_CMD -f tools/valkey-cluster/docker-compose.yml logs valkey-7001' to see cluster logs"
+echo "   - Use '$COMPOSE_CMD -f tools/valkey-cluster/docker-compose.yml down -v' to stop cluster"
 echo "   - Press Ctrl+C to stop development servers"
 echo ""
 

quickstart.sh

@@ -49,7 +49,7 @@ echo "      - Name: Local Valkey Cluster"
 echo ""
 echo "💡 Cluster management:"
 echo "   - Cluster is running in the background"
-echo "   - Use 'docker logs valkey-cluster-valkey-7001-1' to see cluster logs"
-echo "   - Use 'docker compose -f tools/valkey-cluster/docker-compose.yml down -v' to stop cluster"
+echo "   - Use '$COMPOSE_CMD -f tools/valkey-cluster/docker-compose.yml logs valkey-7001' to see cluster logs"
+echo "   - Use '$COMPOSE_CMD -f tools/valkey-cluster/docker-compose.yml down -v' to stop cluster"
 echo ""
 echo "🚀 Enjoy the full Valkey Admin experience with all features!"

scripts/common-setup.sh

@@ -1,6 +1,9 @@
 #!/bin/bash
 # Common setup functions for quickstart scripts
 
+# Select Docker or fall back to Podman; defines compose() and CONTAINER_ENGINE.
+. "$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/tools/common/container-engine.sh"
+
 # Function to detect platform
 detect_platform() {
     PLATFORM="unknown"
@@ -11,7 +14,7 @@ detect_platform() {
         if grep -qi microsoft /proc/version 2>/dev/null; then
             PLATFORM="wsl"
             echo "🐧 WSL (Windows Subsystem for Linux) detected"
-            echo "Make sure Docker Desktop is running with WSL integration enabled"
+            echo "Make sure Docker Desktop (with WSL integration) or Podman is running"
         else
             PLATFORM="linux"
             echo "🐧 Linux detected"
@@ -84,16 +87,17 @@ setup_cluster_env() {
 start_cluster() {
     echo "🗄️  Starting Valkey cluster in background..."
 
-    echo "🐳 Starting Docker containers in background..."
+    echo "🐳 Starting containers with $CONTAINER_ENGINE in background..."
     cd "$TOOLS_DIR"
-    DOCKER_PLATFORM="$DOCKER_PLATFORM" docker compose --profile populate up --build -d
+    export DOCKER_PLATFORM
+    compose --profile populate up --build -d
 
-    # Wait for cluster to be ready
+    # Wait for cluster to be ready (stay in $TOOLS_DIR so `compose` finds the file).
     echo "⏳ Waiting for cluster to be ready..."
-    cd ../..
 
     for i in {1..30}; do
-        if docker exec valkey-cluster-valkey-7001-1 valkey-cli -p 7001 cluster info 2>/dev/null | grep -q "cluster_state:ok"; then
+        cid=$(compose ps -q valkey-7001 2>/dev/null || true)
+        if [ -n "$cid" ] && "$CONTAINER_ENGINE" exec "$cid" valkey-cli -p 7001 cluster info 2>/dev/null | grep -q "cluster_state:ok"; then
             echo "✅ Cluster is ready!"
             break
         fi
@@ -104,6 +108,8 @@ start_cluster() {
         echo "   Checking cluster health... ($i/30)"
         sleep 2
     done
+
+    cd ../..
 }
 
 # Function to run common setup steps

tools/README.md

@@ -1,13 +1,17 @@
 ### Run Sample Instances of Valkey Cluster or Standalone
 
-Docker is a prerequisite as these are Docker containers.
+Docker **or Podman** is a prerequisite. The scripts prefer Docker when its daemon is running and fall back to Podman otherwise; force a choice with `CONTAINER_ENGINE=docker` or `CONTAINER_ENGINE=podman`.
 
 From root run:
 
 `./tools/valkey-standalone/build_run_standalone.sh` for a standalone instance populated with seed data.
 
 `./tools/valkey-cluster/scripts/build_run_cluster.sh` for a cluster instance populated with seed data.
 
+#### Podman notes
+
+Podman 4.x or newer is recommended, and the `podman compose` Compose v2 provider is required (the `podman-compose` v1 tool is not supported). On macOS, run `podman machine start` first. Machines with the `podman-docker` shim are detected as Docker, which works fine.
+
 ### Logical databases
 
 Both stacks expose **16 logical databases** by default. The cluster stack passes `--cluster-databases 16` to every node, and the standalone stack passes `--databases 16`. The `populate.mjs` scripts iterate every configured database and seed each one with the typed sample dataset (string, list, set, hash, sorted set, geo, bitmap, stream) plus a bulk string load.
@@ -33,6 +37,8 @@ POPULATE_DB_COUNT=4 POPULATE_BULK_KEYS=1000 \
   --profile populate run --rm populate
 ```
 
+With Podman, substitute `podman compose` for `docker compose`.
+
 #### Cluster Valkey 9+ baseline
 
 Multiple logical databases on a Valkey **cluster** require Valkey 9.0.0 or newer. The bundled Compose files use `valkey/valkey:latest`, which satisfies the baseline. If you pin an older tag, pin `valkey/valkey:9.0` or newer — otherwise the cluster populate script exits non-zero before issuing any write to a database greater than `0`, naming the detected version and the required baseline.

tools/common/container-engine.sh

@@ -0,0 +1,59 @@
+#!/bin/sh
+# Container engine selection: prefers Docker, falls back to Podman.
+# Source this file (`. .../container-engine.sh`); it defines compose() and
+# exports CONTAINER_ENGINE (docker|podman) and COMPOSE_CMD (display string).
+# Force a specific engine with CONTAINER_ENGINE=docker|podman.
+
+_engine_alive() {
+  command -v "$1" >/dev/null 2>&1 && "$1" info >/dev/null 2>&1
+}
+
+case "${CONTAINER_ENGINE:-}" in
+  docker|podman)
+    if ! _engine_alive "$CONTAINER_ENGINE"; then
+      echo "Error: CONTAINER_ENGINE=$CONTAINER_ENGINE requested, but '$CONTAINER_ENGINE info' failed. Is it installed and running?" >&2
+      exit 1
+    fi
+    ;;
+  "")
+    if _engine_alive docker; then
+      CONTAINER_ENGINE=docker
+    elif _engine_alive podman; then
+      CONTAINER_ENGINE=podman
+    else
+      echo "Error: no working container engine found." >&2
+      echo "  - Docker: install Docker Desktop / docker-ce and start the daemon." >&2
+      echo "  - Podman: install podman (on macOS also run 'podman machine start')." >&2
+      exit 1
+    fi
+    ;;
+  *)
+    echo "Error: unsupported CONTAINER_ENGINE '$CONTAINER_ENGINE' (expected 'docker' or 'podman')." >&2
+    exit 1
+    ;;
+esac
+
+if [ "$CONTAINER_ENGINE" = "docker" ]; then
+  if docker compose version >/dev/null 2>&1; then
+    COMPOSE_CMD="docker compose"
+  else
+    echo "Error: 'docker compose' (Compose v2 plugin) is not available." >&2
+    exit 1
+  fi
+else
+  if podman compose version >/dev/null 2>&1; then
+    COMPOSE_CMD="podman compose"
+  else
+    echo "Error: podman found, but 'podman compose' is not available. Install the docker-compose v2 provider that 'podman compose' delegates to." >&2
+    exit 1
+  fi
+fi
+
+export CONTAINER_ENGINE COMPOSE_CMD
+
+compose() {
+  # shellcheck disable=SC2086  # intentional word-split of a fixed known string
+  $COMPOSE_CMD "$@"
+}
+
+echo "Using container engine: $CONTAINER_ENGINE (compose: $COMPOSE_CMD)"

tools/valkey-cluster/scripts/build_run_cluster.sh

@@ -7,6 +7,9 @@ SCRIPT_DIR=$(cd -- "$(dirname -- "$0")" && pwd)
 # Go up three levels to find the project root.
 PROJECT_ROOT=$(dirname -- "$(dirname -- "$(dirname -- "$SCRIPT_DIR")")")
 
+# Select Docker or fall back to Podman; defines compose() and CONTAINER_ENGINE.
+. "$PROJECT_ROOT/tools/common/container-engine.sh"
+
 # Define all paths as absolute paths from the project root.
 TOOLS_DIR="$PROJECT_ROOT/tools/valkey-cluster"
 ENV_FILE="$TOOLS_DIR/.env"
@@ -35,7 +38,7 @@ ARCH=$(uname -m)
 # Force ARM64 platform since rejson.so is ARM64 and works with emulation
 DOCKER_PLATFORM="linux/arm64"
 
-echo "Detected architecture: $ARCH, using Docker platform: $DOCKER_PLATFORM (forced for rejson.so compatibility)"
+echo "Detected architecture: $ARCH, using container platform: $DOCKER_PLATFORM (forced for rejson.so compatibility)"
 
 # Use sed without the '' flag for Linux compatibility
 if [ "$(uname)" = "Darwin" ]; then
@@ -52,4 +55,5 @@ cd "$TOOLS_DIR"
 echo "Starting Valkey cluster..."
 echo "Keep this terminal open to monitor cluster logs"
 echo ""
-DOCKER_PLATFORM="$DOCKER_PLATFORM" docker compose --profile populate up --build
+export DOCKER_PLATFORM
+compose --profile populate up --build

tools/valkey-standalone/build_run_standalone.sh

@@ -4,6 +4,9 @@ set -eu
 # Resolve script directory so docker-compose can find ./docker-compose.yml regardless of cwd.
 SCRIPT_DIR=$(cd -- "$(dirname -- "$0")" && pwd)
 
+# Select Docker or fall back to Podman; defines compose() and CONTAINER_ENGINE.
+. "$SCRIPT_DIR/../common/container-engine.sh"
+
 # Get IP address - works on both macOS and Linux/WSL
 if command -v ipconfig >/dev/null 2>&1; then
   # macOS
@@ -23,14 +26,21 @@ cd "$SCRIPT_DIR"
 # Defensive cleanup: the previous version of this script created a container with
 # `docker run --name valkey-standalone`. If that stale container still exists on a
 # user's machine, it would collide with `container_name: valkey-standalone` below.
-docker rm -f valkey-standalone >/dev/null 2>&1 || true
+"$CONTAINER_ENGINE" rm -f valkey-standalone >/dev/null 2>&1 || true
 
 echo "Starting Valkey instance on port 6379..."
-docker compose up -d --build --wait valkey-standalone
+# Poll for health instead of `compose up --wait` (a docker-compose-v2-only flag).
+compose up -d --build valkey-standalone
+for i in $(seq 1 30); do
+  status=$("$CONTAINER_ENGINE" inspect --format '{{.State.Health.Status}}' valkey-standalone 2>/dev/null || true)
+  [ "$status" = "healthy" ] && break
+  [ "$i" -eq 30 ] && { echo "Error: valkey-standalone did not become healthy." >&2; exit 1; }
+  sleep 2
+done
 
 echo "Populating Valkey with test data..."
-docker compose --profile populate run --rm populate
+compose --profile populate run --rm populate
 
 echo ""
 echo "Done! Valkey instance running on $ANNOUNCE_IP:6379 (also reachable on localhost:6379)"
-echo "To stop and clean up: docker compose -f tools/valkey-standalone/docker-compose.yml down -v"
+echo "To stop and clean up: $COMPOSE_CMD -f tools/valkey-standalone/docker-compose.yml down -v"