From 1adc774d33a33e96e3b0214a0d01cf06874049ba Mon Sep 17 00:00:00 2001 From: Akshith G Date: Mon, 23 Feb 2026 09:15:34 -0800 Subject: [PATCH] docs: add Colima and docker-buildx setup instructions for macOS (#474) macOS users using Colima instead of Docker Desktop were hitting missing buildx errors and had no documentation to guide them. Add Colima as a supported Docker runtime, document buildx installation, and ensure setup-local installs buildx automatically. Co-authored-by: Claude Opus 4.6 --- README.md | 9 +++++++++ deployment/README.md | 28 +++++++++++++++++++++++----- scripts/common.sh | 37 +++++++++++++++++++++++++++++++++++++ 3 files changed, 69 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index a283188e..610c7d66 100644 --- a/README.md +++ b/README.md @@ -28,6 +28,7 @@ ### Supported Systems - **Linux x86_64** (fully supported) +- **macOS** (local development supported via Docker Desktop or Colima) - **ARM64** (partial support for upstream Google OSS-Fuzz projects) ### Required System Packages @@ -75,6 +76,14 @@ This script will install all dependencies, configure the environment, and guide **Note:** If you prefer manual setup, see the [Manual Setup Guide](guides/MANUAL_SETUP.md). +1. Ensure Docker is running before deploying: + +```bash +# Docker Desktop: start the application +# Colima (macOS/Linux alternative): +colima start --cpu 6 --memory 10 --disk 80 +``` + 1. Start Buttercup locally ```bash diff --git a/deployment/README.md b/deployment/README.md index f547214e..5f78105a 100644 --- a/deployment/README.md +++ b/deployment/README.md @@ -32,16 +32,17 @@ This section covers deploying the CRS locally using minikube on macOS or Linux. ### Local Prerequisites -- **Docker Desktop** (macOS/Windows) or Docker Engine (Linux) +- **Docker Desktop** (macOS/Windows), **Colima** (macOS/Linux), or Docker Engine (Linux) +- **docker-buildx**: Required for building images (`brew install docker-buildx` on macOS) - **minikube**: `brew install minikube` (macOS) or see [minikube install docs](https://minikube.sigs.k8s.io/docs/start/) - **helm**: `brew install helm` (macOS) - **kubectl**: `brew install kubectl` (macOS) -### Docker Desktop Resource Configuration +### Docker Resource Configuration -Docker Desktop has default resource limits that are typically too low for the full CRS deployment. +The Docker runtime must have enough resources allocated for the full CRS deployment. -**To configure Docker Desktop resources (macOS):** +**Docker Desktop (macOS/Windows):** 1. Open Docker Desktop > Settings > Resources 2. Allocate at least: - CPUs: 4-6 (depending on your machine) @@ -49,7 +50,24 @@ Docker Desktop has default resource limits that are typically too low for the fu - Disk: 80+ GB 3. Click "Apply & Restart" -**Important**: Minikube cannot use more resources than Docker Desktop allocates. If `env.template` specifies `MINIKUBE_CPU=6` and `MINIKUBE_MEMORY_GB=10`, but Docker Desktop only has 4 CPUs and 8GB RAM, minikube will fail to start or pods will remain Pending. +**Colima (macOS/Linux):** +```bash +colima start --cpu 6 --memory 10 --disk 80 +``` + +After starting Colima, ensure the buildx plugin is linked: +```bash +brew install docker-buildx +``` + +`docker-buildx` is a Docker plugin. For Docker to find the plugin, add "cliPluginsExtraDirs" to ~/.docker/config.json: +```json +"cliPluginsExtraDirs": [ + "/opt/homebrew/lib/docker/cli-plugins" +] +``` + +**Important**: Minikube cannot use more resources than the Docker runtime allocates. If `env.template` specifies `MINIKUBE_CPU=6` and `MINIKUBE_MEMORY_GB=10`, but Docker only has 4 CPUs and 8GB RAM, minikube will fail to start or pods will remain Pending. ### Quick Start diff --git a/scripts/common.sh b/scripts/common.sh index b6316baa..8b3a22b9 100755 --- a/scripts/common.sh +++ b/scripts/common.sh @@ -807,6 +807,31 @@ check_brew() { fi } +# Register Homebrew cli-plugins dir so Docker discovers plugins like +# buildx. Prefers patching ~/.docker/config.json via jq; falls back +# to a per-plugin symlink when jq is not installed. +ensure_docker_cli_plugins_dir() { + local plugins_dir="/opt/homebrew/lib/docker/cli-plugins" + local config_file="$HOME/.docker/config.json" + + if command_exists jq; then + mkdir -p "$(dirname "$config_file")" + if [ ! -f "$config_file" ]; then + echo '{}' > "$config_file" + fi + # Idempotent: appends only if the path isn't already listed + local tmp="${config_file}.tmp" + jq --arg d "$plugins_dir" \ + '.cliPluginsExtraDirs = ((.cliPluginsExtraDirs // []) | if index($d) then . else . + [$d] end)' \ + "$config_file" > "$tmp" && mv "$tmp" "$config_file" + else + print_warning "jq not found — falling back to symlink for docker-buildx" + mkdir -p ~/.docker/cli-plugins + ln -sfn "$(brew --prefix docker-buildx)/lib/docker/cli-plugins/docker-buildx" \ + ~/.docker/cli-plugins/docker-buildx + fi +} + install_docker_mac() { if command_exists docker; then print_success "Docker is already installed" @@ -814,6 +839,18 @@ install_docker_mac() { print_status "Installing Docker..." brew install --cask docker fi + + # Ensure docker-buildx is available (bundled with Docker Desktop, + # but must be installed separately for Colima users) + if ! docker buildx version >/dev/null 2>&1; then + print_status "Installing docker-buildx plugin..." + brew install docker-buildx + # Register Homebrew cli-plugins dir so Docker discovers buildx + ensure_docker_cli_plugins_dir + print_success "docker-buildx installed" + else + print_success "docker-buildx is available" + fi } install_uv_mac() {