WA-CI-010: Script CI system prerequisites

.github/workflows/ci.yml

@@ -109,8 +109,8 @@ jobs:
         ruby-version: 3.2
         bundler-cache: true
 
-    - name: Install system deps (docker-compose + ImageMagick)
-      run: sudo apt-get update && sudo apt-get install -y docker-compose imagemagick
+    - name: System prerequisites
+      run: script/system_prereqs
     - uses: workarea-commerce/ci/test@v1
       with:
         command: cd admin && bin/rails test -b
@@ -124,8 +124,8 @@ jobs:
         ruby-version: 3.2
         bundler-cache: true
 
-    - name: Install system deps (docker-compose + ImageMagick)
-      run: sudo apt-get update && sudo apt-get install -y docker-compose imagemagick
+    - name: System prerequisites
+      run: script/system_prereqs
     - uses: workarea-commerce/ci/test@v1
       with:
         command: cd admin && bin/rails teaspoon
@@ -139,8 +139,8 @@ jobs:
         ruby-version: 3.2
         bundler-cache: true
 
-    - name: Install system deps (docker-compose + ImageMagick)
-      run: sudo apt-get update && sudo apt-get install -y docker-compose imagemagick
+    - name: System prerequisites
+      run: script/system_prereqs
     - uses: workarea-commerce/ci/test@v1
       with:
         command: cd admin && bin/rails test test/system/**/*_test.rb -b
@@ -159,8 +159,8 @@ jobs:
         ruby-version: 3.2
         bundler-cache: true
 
-    - name: Install system deps (docker-compose + ImageMagick)
-      run: sudo apt-get update && sudo apt-get install -y docker-compose imagemagick
+    - name: System prerequisites
+      run: script/system_prereqs
     - uses: workarea-commerce/ci/test@v1
       with:
         command: cd core && bin/rails teaspoon
@@ -174,8 +174,8 @@ jobs:
         ruby-version: 3.2
         bundler-cache: true
 
-    - name: Install system deps (docker-compose + ImageMagick)
-      run: sudo apt-get update && sudo apt-get install -y docker-compose imagemagick
+    - name: System prerequisites
+      run: script/system_prereqs
     - uses: workarea-commerce/ci/test@v1
       with:
         command: cd core && bin/rails test test/**/*_test.rb -b
@@ -189,8 +189,8 @@ jobs:
         ruby-version: 3.2
         bundler-cache: true
 
-    - name: Install system deps (docker-compose + ImageMagick)
-      run: sudo apt-get update && sudo apt-get install -y docker-compose imagemagick
+    - name: System prerequisites
+      run: script/system_prereqs
     - uses: workarea-commerce/ci/test@v1
       with:
         command: cd storefront && bin/rails test -b
@@ -204,8 +204,8 @@ jobs:
         ruby-version: 3.2
         bundler-cache: true
 
-    - name: Install system deps (docker-compose + ImageMagick)
-      run: sudo apt-get update && sudo apt-get install -y docker-compose imagemagick
+    - name: System prerequisites
+      run: script/system_prereqs
     - uses: workarea-commerce/ci/test@v1
       with:
         command: cd storefront && bin/rails teaspoon
@@ -219,8 +219,8 @@ jobs:
         ruby-version: 3.2
         bundler-cache: true
 
-    - name: Install system deps (docker-compose + ImageMagick)
-      run: sudo apt-get update && sudo apt-get install -y docker-compose imagemagick
+    - name: System prerequisites
+      run: script/system_prereqs
     - uses: workarea-commerce/ci/test@v1
       with:
         command: cd storefront && bin/rails test test/system/**/*_test.rb -b
@@ -259,8 +259,8 @@ jobs:
         ruby-version: '3.3'
         bundler-cache: true
 
-    - name: Install system deps (docker-compose + ImageMagick)
-      run: sudo apt-get update && sudo apt-get install -y docker-compose imagemagick
+    - name: System prerequisites
+      run: script/system_prereqs
 
     - uses: workarea-commerce/ci/test@v1
       with:
@@ -299,8 +299,8 @@ jobs:
       run: bundle install
       continue-on-error: ${{ matrix.experimental }}
 
-    - name: Install system deps (docker-compose + ImageMagick)
-      run: sudo apt-get update && sudo apt-get install -y docker-compose imagemagick
+    - name: System prerequisites
+      run: script/system_prereqs
 
     - uses: workarea-commerce/ci/test@v1
       if: steps.bundle.outcome == 'success'

core/lib/workarea/tasks/services.rb

@@ -3,8 +3,20 @@ module Tasks
     module Services
       extend self
 
+      # Returns the compose command to use: "docker compose" (plugin) or
+      # "docker-compose" (standalone). Returns nil when neither is available.
+      def compose_command
+        return @compose_command if defined?(@compose_command)
+        @compose_command =
+          if system('docker compose version > /dev/null 2>&1')
+            'docker compose'
+          elsif system('docker-compose -v > /dev/null 2>&1')
+            'docker-compose'
+          end
+      end
+
       def assert_docker_compose_installed!
-        unless system('docker-compose -v > /dev/null 2>&1')
+        unless compose_command
           STDERR.puts <<~eos
   **************************************************
   ⛔️ ERROR: workarea:services tasks depend on Docker Compose being installed. \
@@ -40,7 +52,7 @@ def compose_env
       def up
         assert_docker_compose_installed!
 
-        if system(compose_env, "docker-compose up -d #{ENV['COMPOSE_ARGUMENTS']} #{ENV['WORKAREA_SERVICES']}")
+        if system(compose_env, "#{compose_command} up -d #{ENV['COMPOSE_ARGUMENTS']} #{ENV['WORKAREA_SERVICES']}")
           puts '✅ Success! Workarea services are running in the background. Run workarea:services:down to stop them.'
         else
           STDERR.puts '⛔️ Error! There was an error starting Workarea services.'
@@ -50,7 +62,7 @@ def up
       def down
         assert_docker_compose_installed!
 
-        if system(compose_env, "docker-compose down #{ENV['COMPOSE_ARGUMENTS']}")
+        if system(compose_env, "#{compose_command} down #{ENV['COMPOSE_ARGUMENTS']}")
           puts '✅ Success! Workarea services are stopped. Run workarea:services:up to start them.'
         else
           STDERR.puts '⛔️ Error! There was an error stopping Workarea services.'
@@ -60,7 +72,7 @@ def down
       def clean
         assert_docker_compose_installed!
 
-        if system(compose_env, "docker-compose down -v #{ENV['COMPOSE_ARGUMENTS']}")
+        if system(compose_env, "#{compose_command} down -v #{ENV['COMPOSE_ARGUMENTS']}")
           puts '✅ Success! Workarea service volumes have been removed. Run workarea:services:up to start services and recreate volumes.'
         else
           STDERR.puts '⛔️ Error! There was an error removing Workarea service volumes.'

script/system_prereqs

@@ -0,0 +1,186 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'USAGE'
+Usage: script/system_prereqs [--verify]
+
+Installs and/or verifies system prerequisites used by CI.
+
+Options:
+  --verify   Only verify prerequisites (do not install)
+USAGE
+}
+
+VERIFY_ONLY=false
+
+case "${1:-}" in
+  "") ;;
+  --verify) VERIFY_ONLY=true ;;
+  -h|--help) usage; exit 0 ;;
+  *)
+    echo "Unknown argument: $1" >&2
+    usage >&2
+    exit 2
+    ;;
+esac
+
+log() { echo "[system_prereqs] $*"; }
+fail() { echo "[system_prereqs] ERROR: $*" >&2; exit 1; }
+
+have() { command -v "$1" >/dev/null 2>&1; }
+
+have_compose() {
+  (have docker && docker compose version >/dev/null 2>&1) || have docker-compose
+}
+
+print_versions() {
+  log "Versions:"
+
+  if have docker; then
+    docker --version | sed 's/^/[system_prereqs]   /'
+  else
+    log "  docker: (missing)"
+  fi
+
+  if have docker && docker compose version >/dev/null 2>&1; then
+    docker compose version | head -n 1 | sed 's/^/[system_prereqs]   /'
+  elif have docker-compose; then
+    docker-compose --version | sed 's/^/[system_prereqs]   /'
+  else
+    log "  docker compose: (missing)"
+  fi
+
+  if have convert; then
+    convert --version | head -n 1 | sed 's/^/[system_prereqs]   /'
+  else
+    log "  convert: (missing)"
+  fi
+}
+
+check_prereqs() {
+  local print_missing="${1:-false}"
+  local missing=false
+
+  if ! have docker; then
+    [[ "$print_missing" == "true" ]] && echo "[system_prereqs] Missing: docker" >&2
+    missing=true
+  fi
+
+  if ! have_compose; then
+    [[ "$print_missing" == "true" ]] && echo "[system_prereqs] Missing: docker compose (docker compose or docker-compose)" >&2
+    missing=true
+  fi
+
+  if ! have convert; then
+    [[ "$print_missing" == "true" ]] && echo "[system_prereqs] Missing: ImageMagick (convert)" >&2
+    missing=true
+  fi
+
+  [[ "$missing" == "true" ]] && return 1
+  return 0
+}
+
+verify() {
+  if ! check_prereqs true; then
+    print_versions
+    fail "One or more prerequisites are missing"
+  fi
+
+  print_versions
+  log "All prerequisites satisfied"
+}
+
+install_debian_like() {
+  # Verify-first: GitHub-hosted runners typically already have Docker + Compose.
+  # Only attempt installation when something is missing.
+  if [[ "$VERIFY_ONLY" == "true" ]]; then
+    verify
+    return
+  fi
+
+  if check_prereqs false; then
+    log "Prerequisites already satisfied; skipping installation."
+    verify
+    return
+  fi
+
+  local missing_docker=false
+  local missing_convert=false
+
+  have docker || missing_docker=true
+  have convert || missing_convert=true
+
+  if [[ "$missing_docker" == "true" || "$missing_convert" == "true" ]]; then
+    if ! have sudo; then
+      print_versions
+      fail "Missing prerequisites and sudo is required to install them"
+    fi
+
+    log "Updating apt package lists"
+    sudo apt-get update
+  fi
+
+  if [[ "$missing_docker" == "true" ]]; then
+    # Install Docker only when missing.
+    # We use the distro package to avoid setting up Docker's official apt repo.
+    log "Installing Docker via apt (docker.io)"
+    sudo apt-get install -y docker.io
+  fi
+
+  # We intentionally do NOT install Docker Compose via apt.
+  # GitHub runners provide either the `docker compose` plugin or `docker-compose`.
+  # If it's missing, ask the user/environment to provide it.
+  if ! have_compose; then
+    if have docker && docker compose version >/dev/null 2>&1; then
+      log "docker compose available (plugin)"
+    elif have docker-compose; then
+      log "docker-compose available (standalone)"
+    else
+      print_versions
+      fail "Docker Compose is missing. Please install Docker Compose (plugin or standalone), then re-run."
+    fi
+  fi
+
+  if [[ "$missing_convert" == "true" ]]; then
+    log "Installing ImageMagick via apt"
+    sudo apt-get install -y imagemagick
+  fi
+
+  verify
+}
+
+main() {
+  local uname_out
+  uname_out="$(uname -s)"
+
+  case "$uname_out" in
+    Darwin)
+      log "macOS detected; skipping system package installation."
+      if [[ "$VERIFY_ONLY" == "true" ]]; then
+        log "--verify is best-effort on macOS; printing versions when present."
+        print_versions
+      fi
+      exit 0
+      ;;
+    Linux)
+      if [[ -f /etc/os-release ]]; then
+        # shellcheck disable=SC1091
+        . /etc/os-release
+        case "${ID_LIKE:-$ID}" in
+          *debian*|*ubuntu*)
+            install_debian_like
+            exit 0
+            ;;
+        esac
+      fi
+
+      fail "Unsupported Linux distribution. Only Ubuntu/Debian are supported by this script."
+      ;;
+    *)
+      fail "Unsupported OS: $uname_out"
+      ;;
+  esac
+}
+
+main