From a64ab377a89f411069ffbf9217d6c6c061539373 Mon Sep 17 00:00:00 2001 From: Argus Li Date: Wed, 29 Jul 2026 15:06:52 -0700 Subject: [PATCH] Add podman compose fallback. Signed-off-by: Argus Li --- .../content/docs/development/contributing.md | 4 ++ quickstart-web.sh | 4 +- quickstart.sh | 4 +- scripts/common-setup.sh | 18 ++++-- tools/README.md | 8 ++- tools/common/container-engine.sh | 59 +++++++++++++++++++ .../scripts/build_run_cluster.sh | 8 ++- .../valkey-standalone/build_run_standalone.sh | 18 ++++-- 8 files changed, 106 insertions(+), 17 deletions(-) create mode 100644 tools/common/container-engine.sh diff --git a/docs-site/src/content/docs/development/contributing.md b/docs-site/src/content/docs/development/contributing.md index 9de019c2..0346e857 100644 --- a/docs-site/src/content/docs/development/contributing.md +++ b/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 diff --git a/quickstart-web.sh b/quickstart-web.sh index 2c7b0ce8..dd87b034 100644 --- a/quickstart-web.sh +++ b/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 "" diff --git a/quickstart.sh b/quickstart.sh index 8ee89fbb..e7cd5f55 100755 --- a/quickstart.sh +++ b/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!" diff --git a/scripts/common-setup.sh b/scripts/common-setup.sh index b3ceb98e..fe4bb698 100644 --- a/scripts/common-setup.sh +++ b/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 diff --git a/tools/README.md b/tools/README.md index 7be00e8e..458233bb 100644 --- a/tools/README.md +++ b/tools/README.md @@ -1,6 +1,6 @@ ### 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: @@ -8,6 +8,10 @@ From root run: `./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. diff --git a/tools/common/container-engine.sh b/tools/common/container-engine.sh new file mode 100644 index 00000000..6b877cf9 --- /dev/null +++ b/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)" diff --git a/tools/valkey-cluster/scripts/build_run_cluster.sh b/tools/valkey-cluster/scripts/build_run_cluster.sh index 21499b5a..2fd6467a 100755 --- a/tools/valkey-cluster/scripts/build_run_cluster.sh +++ b/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 diff --git a/tools/valkey-standalone/build_run_standalone.sh b/tools/valkey-standalone/build_run_standalone.sh index f3c1c1d1..964d56a0 100755 --- a/tools/valkey-standalone/build_run_standalone.sh +++ b/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"