From eea0a86c85d6e2a6a614f2cb7072a28ac99cd172 Mon Sep 17 00:00:00 2001
From: "Mason Kim(ZINUS US_SALES)" <mkim@zinus.com>
Date: Wed, 15 Apr 2026 16:18:36 -0400
Subject: [PATCH] fix: align compose checks with docker compose

Signed-off-by: Mason Kim(ZINUS US_SALES) <mkim@zinus.com>
---
 backend/cmd/installer/checker/helpers.go      | 15 +++---
 backend/cmd/installer/checker/helpers_test.go | 46 +++++++++++++++++++
 backend/cmd/installer/wizard/locale/locale.go | 20 ++++----
 3 files changed, 66 insertions(+), 15 deletions(-)

diff --git a/backend/cmd/installer/checker/helpers.go b/backend/cmd/installer/checker/helpers.go
index 4a7814b..612364b 100644
--- a/backend/cmd/installer/checker/helpers.go
+++ b/backend/cmd/installer/checker/helpers.go
@@ -236,14 +236,15 @@ func checkDockerCliVersion() DockerVersion {
 }
 
 func checkDockerComposeVersion() DockerVersion {
-	cmd := exec.Command("docker", "compose", "version")
-	output, err := cmd.Output()
+	return checkDockerComposeVersionWithRunner(func(name string, args ...string) ([]byte, error) {
+		return exec.Command(name, args...).Output()
+	})
+}
+
+func checkDockerComposeVersionWithRunner(run func(name string, args ...string) ([]byte, error)) DockerVersion {
+	output, err := run("docker", "compose", "version")
 	if err != nil {
-		cmd = exec.Command("docker-compose", "--version")
-		output, err = cmd.Output()
-		if err != nil {
-			return DockerVersion{Version: "", Valid: false}
-		}
+		return DockerVersion{Version: "", Valid: false}
 	}
 
 	versionStr := extractVersionFromOutput(string(output))
diff --git a/backend/cmd/installer/checker/helpers_test.go b/backend/cmd/installer/checker/helpers_test.go
index 481d86c..e2b65d9 100644
--- a/backend/cmd/installer/checker/helpers_test.go
+++ b/backend/cmd/installer/checker/helpers_test.go
@@ -2,6 +2,7 @@ package checker
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"net/http"
 	"net/http/httptest"
@@ -157,6 +158,51 @@ func TestExtractVersionFromOutput(t *testing.T) {
 	}
 }
 
+func TestCheckDockerComposeVersionWithRunner(t *testing.T) {
+	t.Run("uses docker compose v2 output", func(t *testing.T) {
+		calls := 0
+		result := checkDockerComposeVersionWithRunner(func(name string, args ...string) ([]byte, error) {
+			calls++
+			if name != "docker" {
+				t.Fatalf("unexpected command %q", name)
+			}
+			if len(args) != 2 || args[0] != "compose" || args[1] != "version" {
+				t.Fatalf("unexpected args: %v", args)
+			}
+
+			return []byte("Docker Compose version v2.12.2"), nil
+		})
+
+		if calls != 1 {
+			t.Fatalf("expected 1 command invocation, got %d", calls)
+		}
+		if result.Version != "2.12.2" {
+			t.Fatalf("expected version 2.12.2, got %q", result.Version)
+		}
+		if !result.Valid {
+			t.Fatal("expected docker compose version to be valid")
+		}
+	})
+
+	t.Run("fails when docker compose is unavailable", func(t *testing.T) {
+		calls := 0
+		result := checkDockerComposeVersionWithRunner(func(name string, args ...string) ([]byte, error) {
+			calls++
+			return nil, errors.New("executable file not found")
+		})
+
+		if calls != 1 {
+			t.Fatalf("expected 1 command invocation, got %d", calls)
+		}
+		if result.Version != "" {
+			t.Fatalf("expected empty version, got %q", result.Version)
+		}
+		if result.Valid {
+			t.Fatal("expected docker compose check to be invalid")
+		}
+	})
+}
+
 func TestCheckVersionCompatibility(t *testing.T) {
 	tests := []struct {
 		version    string
diff --git a/backend/cmd/installer/wizard/locale/locale.go b/backend/cmd/installer/wizard/locale/locale.go
index b7c7f36..3fb0a3f 100644
--- a/backend/cmd/installer/wizard/locale/locale.go
+++ b/backend/cmd/installer/wizard/locale/locale.go
@@ -155,23 +155,27 @@ Required: 20.0.0+`
 
 	// Docker Compose issues
 	TroubleshootComposeTitle = "Docker Compose Not Found"
-	TroubleshootComposeDesc  = "Docker Compose is required but not installed or not in PATH."
+	TroubleshootComposeDesc  = "The Docker Compose v2 plugin is required, but `docker compose` is not available."
 	TroubleshootComposeFix   = `To fix:
-1. Install Docker Desktop (includes Compose) or
-2. Install standalone: https://docs.docker.com/compose/install/
+1. Install or update Docker Desktop, or install the Docker Compose v2 plugin for Docker Engine
+2. Verify the plugin is available: docker compose version
+3. If only legacy docker-compose is installed, remove it or install the v2 plugin as well
 
-Verify installation: docker compose version`
+PentAGI executes "docker compose", so legacy "docker-compose" alone is not sufficient.
+Documentation: https://docs.docker.com/compose/install/`
 
 	// Docker Compose version issues
 	TroubleshootComposeVersionTitle = "Docker Compose Version Too Old"
-	TroubleshootComposeVersionDesc  = "Your Docker Compose version is incompatible. PentAGI requires Docker Compose 1.25.0 or newer."
+	TroubleshootComposeVersionDesc  = "Your `docker compose` version is incompatible. PentAGI requires Docker Compose 1.25.0 or newer."
 	TroubleshootComposeVersionFix   = `Current version: %s
 Required: 1.25.0+
 
 To fix:
-1. Update Docker Desktop to latest version
-2. Or install newer Docker Compose:
-   https://docs.docker.com/compose/install/`
+1. Update Docker Desktop or the Docker Compose v2 plugin to a newer version
+2. Verify the result with: docker compose version
+3. If only legacy docker-compose is installed, install the v2 plugin as well
+
+Documentation: https://docs.docker.com/compose/install/`
 
 	// Worker environment issues
 	TroubleshootWorkerTitle = "Worker Docker Environment Not Accessible"