From 990a5d0845c3e0a0e9adc570586d32189834360f Mon Sep 17 00:00:00 2001 From: dyllon Date: Mon, 27 Apr 2026 13:55:19 +0800 Subject: [PATCH] docs: clarify optional Docker and Kubernetes tools --- .../AppStateBackendAggregationTests.swift | 56 +++++++++++++++++++ ColimaStackTests/ColimaStackTests.swift | 36 ++++++++++++ README.md | 22 ++++++-- docs/src/content/docs/architecture.md | 6 +- docs/src/content/docs/compare/orbstack.md | 4 +- docs/src/content/docs/faq.md | 4 ++ docs/src/content/docs/features.md | 8 +-- docs/src/content/docs/features/diagnostics.md | 4 +- docs/src/content/docs/index.md | 8 +-- docs/src/content/docs/install.md | 25 ++++++--- docs/src/content/docs/kubernetes/overview.md | 2 +- docs/src/content/docs/quick-start.md | 12 ++-- .../src/content/docs/reference/command-api.md | 6 +- docs/src/content/docs/troubleshooting.md | 4 +- 14 files changed, 158 insertions(+), 39 deletions(-) diff --git a/ColimaStackTests/AppStateBackendAggregationTests.swift b/ColimaStackTests/AppStateBackendAggregationTests.swift index ed24676..80fbeb1 100644 --- a/ColimaStackTests/AppStateBackendAggregationTests.swift +++ b/ColimaStackTests/AppStateBackendAggregationTests.swift @@ -298,6 +298,26 @@ struct AppStateBackendAggregationTests { #expect(snapshot.docker == nil) } + @Test func backendSnapshotReturnsIssuesWhenOptionalResourceProvidersFail() async { + let service = LiveBackendSnapshotService( + dockerService: FailingDockerResourceProvider(), + kubernetesService: FailingKubernetesResourceProvider() + ) + var profile = Self.profile(named: "default", state: .running) + profile.kubernetes = KubernetesConfig(enabled: true, version: "v1.30.4+k3s1", context: "colima") + var status = Self.detail(profile: "default", state: .running) + status.kubernetes = profile.kubernetes + + let snapshot = await service.snapshot(profile: profile, status: status) + + #expect(snapshot.profile.name == "default") + #expect(snapshot.status.state == .running) + #expect(snapshot.docker == nil) + #expect(snapshot.kubernetes == nil) + #expect(snapshot.issues.contains { $0.source == .docker && $0.title == "Unable to load Docker resources" }) + #expect(snapshot.issues.contains { $0.source == .kubernetes && $0.title == "Unable to load Kubernetes resources" }) + } + fileprivate static func profile(named name: String, state: ProfileState) -> ColimaProfile { ColimaProfile( name: name, @@ -441,6 +461,42 @@ private struct EmptyKubernetesResourceProvider: KubernetesResourceProviding { } } +private struct FailingDockerResourceProvider: DockerResourceProviding { + func loadSnapshot(context: String?) async -> ResourceLoadState { + .failed( + BackendIssue( + severity: .error, + source: .docker, + title: "Unable to load Docker resources", + message: "docker: command not found" + ), + lastValue: nil + ) + } + + func snapshot(context: String?) async throws -> DockerResourceSnapshot { + throw AppStateAggregationTestError(message: "docker: command not found") + } +} + +private struct FailingKubernetesResourceProvider: KubernetesResourceProviding { + func loadSnapshot(context: String?) async -> ResourceLoadState { + .failed( + BackendIssue( + severity: .error, + source: .kubernetes, + title: "Unable to load Kubernetes resources", + message: "kubectl: command not found" + ), + lastValue: nil + ) + } + + func snapshot(context: String?) async throws -> KubernetesResourceSnapshot { + throw AppStateAggregationTestError(message: "kubectl: command not found") + } +} + @MainActor private final class RecordingFakeColima: ColimaControlling { var profiles: [ColimaProfile] diff --git a/ColimaStackTests/ColimaStackTests.swift b/ColimaStackTests/ColimaStackTests.swift index f7058b8..566a8c9 100644 --- a/ColimaStackTests/ColimaStackTests.swift +++ b/ColimaStackTests/ColimaStackTests.swift @@ -295,6 +295,42 @@ struct ColimaCLITests { #expect(diagnostics.docker.error == "Colima default is stopped") } + @Test func diagnosticsTreatsDockerKubectlAndLimaAsOptionalWhenMissing() async throws { + let runner = FakeProcessRunner(results: [ + "version": ProcessResult( + request: ProcessRequest(arguments: ["colima", "version"]), + exitCode: 0, + stdout: "colima version 0.10.1", + stderr: "" + ), + "colima status --json": ProcessResult( + request: ProcessRequest(arguments: ["colima", "status", "--json"], environment: ["COLIMA_PROFILE": "default"]), + exitCode: 0, + stdout: #"{"display_name":"colima","runtime":"containerd","kubernetes":false}"#, + stderr: "" + ) + ]) + let cli = LiveColimaCLI( + processRunner: runner, + toolLocator: FakeToolLocator(urls: [ + "colima": URL(fileURLWithPath: "/opt/homebrew/bin/colima") + ]) + ) + + let diagnostics = await cli.diagnostics() + + #expect(diagnostics.tools.first(where: { $0.id == "colima" })?.availability == .available(path: "/opt/homebrew/bin/colima", version: "colima version 0.10.1")) + #expect(diagnostics.tools.first(where: { $0.id == "docker" })?.availability == .missing) + #expect(diagnostics.tools.first(where: { $0.id == "kubectl" })?.availability == .missing) + #expect(diagnostics.tools.first(where: { $0.id == "limactl" })?.availability == .missing) + #expect(diagnostics.colima.state == .running) + #expect(diagnostics.colima.runtime == .containerd) + #expect(!diagnostics.docker.available) + #expect(diagnostics.docker.error == "Not installed") + #expect(diagnostics.messages.isEmpty) + #expect(runner.requests.allSatisfy { $0.executableURL.lastPathComponent == "colima" }) + } + @Test func diagnosticsUsesExplicitColimaDockerContextWhenActiveContextDiffers() async throws { let runner = FakeProcessRunner(results: [ "version": ProcessResult( diff --git a/README.md b/README.md index 3d394d8..108647b 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ ColimaStack gives [Colima](https://github.com/abiosoft/colima) a focused graphical workspace for local container development. It helps you inspect runtime health, manage profiles, browse Docker inventory, view Kubernetes resources, and diagnose toolchain issues without hiding the command-line tools doing the work. > [!NOTE] -> ColimaStack is not a container engine. It controls and inspects local tools such as `colima`, `docker`, `kubectl`, and `limactl`. +> ColimaStack is not a container engine. It controls and inspects local tools such as `colima`, plus optional integrations like `docker`, `kubectl`, and `limactl` when those tools are installed. ## Features @@ -17,20 +17,30 @@ ColimaStack gives [Colima](https://github.com/abiosoft/colima) a focused graphic - **Runtime overview**: view profile state, Docker context, socket, address, resources, Kubernetes status, recent activity, and logs. - **Docker inventory**: browse containers, images, volumes, networks, runtime stats, and Docker disk usage. - **Kubernetes visibility**: inspect nodes, namespaces, pods, deployments, services, and metrics when Kubernetes is enabled. -- **Diagnostics**: check `colima`, `docker`, `kubectl`, `limactl`, Docker context, and Kubernetes context health. +- **Diagnostics**: check `colima`, optional tool availability, Docker context, and Kubernetes context health. - **Command transparency**: review active operations, command history, stdout, stderr, and Colima daemon logs. - **Menu bar access**: check runtime state and jump back into the main workspace from the macOS menu bar. ## Requirements - macOS 14 or later -- Homebrew-managed CLI dependencies for the default Docker workflow: +- Homebrew-managed Colima CLI: ```sh -brew install colima docker +brew install colima ``` -Install `kubectl` only for Kubernetes workflows. Homebrew normally installs Lima with Colima; if diagnostics report that `limactl` is missing, install Lima explicitly. +Optional tools unlock additional views and diagnostics: + +- Install the Docker CLI only if you want Docker runtime inventory such as containers, images, volumes, networks, stats, and disk usage. +- Install `kubectl` only for Kubernetes workflows. +- Homebrew normally installs Lima with Colima; if diagnostics report that `limactl` is missing, install Lima explicitly. + +```sh +brew install docker +brew install kubectl +brew install lima +``` ## Documentation @@ -47,7 +57,7 @@ If you want to contribute, see [CONTRIBUTING.md](CONTRIBUTING.md) for local deve ## How It Works -ColimaStack is a local-first macOS app. It calls the Colima CLI for profile lifecycle operations, uses Docker CLI JSON output for runtime inventory, reads Kubernetes state through `kubectl`, and loads selected Colima files such as profile configuration, SSH config, and daemon logs. +ColimaStack is a local-first macOS app. It calls the Colima CLI for profile lifecycle operations, uses Docker CLI JSON output for Docker runtime inventory when the Docker CLI is installed, reads Kubernetes state through `kubectl` when Kubernetes support is installed, and loads selected Colima files such as profile configuration, SSH config, and daemon logs. Most profile-scoped operations use the `COLIMA_PROFILE` environment variable so the active app selection maps directly to the intended Colima runtime. diff --git a/docs/src/content/docs/architecture.md b/docs/src/content/docs/architecture.md index 0caca47..764cf46 100644 --- a/docs/src/content/docs/architecture.md +++ b/docs/src/content/docs/architecture.md @@ -1,6 +1,6 @@ --- title: Architecture -description: How ColimaStack connects the macOS app, Colima CLI, Docker CLI, kubectl, and local Colima files. +description: How ColimaStack connects the macOS app, Colima CLI, optional Docker CLI and kubectl integrations, and local Colima files. --- ColimaStack is a native macOS GUI backed by local command-line tools and file-backed Colima configuration. @@ -26,7 +26,7 @@ Most profile-scoped operations use the `COLIMA_PROFILE` environment variable. ## Docker inventory -Docker resources are read through the Docker CLI using JSON output where available: +When the Docker CLI is installed and the selected profile uses the Docker runtime, Docker resources are read through JSON output where available: - `docker ps -a --format json` - `docker images --format json` @@ -37,7 +37,7 @@ Docker resources are read through the Docker CLI using JSON output where availab ## Kubernetes inventory -Kubernetes resources are read through `kubectl`: +When `kubectl` is installed, Kubernetes resources are read through `kubectl`: - `kubectl get nodes -o json` - `kubectl get namespaces -o json` diff --git a/docs/src/content/docs/compare/orbstack.md b/docs/src/content/docs/compare/orbstack.md index bb6b693..eb1e624 100644 --- a/docs/src/content/docs/compare/orbstack.md +++ b/docs/src/content/docs/compare/orbstack.md @@ -5,7 +5,7 @@ description: Compare ColimaStack's Colima-focused workflow with OrbStack's bundl OrbStack is a bundled macOS product for Docker containers, Kubernetes, and Linux machines. Its docs emphasize out-of-the-box installation, automatic container domains, HTTPS, GUI management, command-line usage, Docker Desktop and Colima migration, Kubernetes integration, and Linux machine workflows. -ColimaStack takes a different route: it builds a native GUI and diagnostics layer around Colima, Docker CLI, kubectl, and Lima. +ColimaStack takes a different route: it builds a native GUI and diagnostics layer around Colima, with optional Docker CLI, kubectl, and Lima integrations. ## Choose ColimaStack when @@ -13,7 +13,7 @@ ColimaStack takes a different route: it builds a native GUI and diagnostics laye - you already use Colima profiles - you want GUI visibility without replacing your Colima setup - you need command transparency and CLI compatibility -- you want Docker and Kubernetes inventory for Colima contexts +- you want optional Docker and Kubernetes inventory for Colima contexts ## Choose OrbStack when diff --git a/docs/src/content/docs/faq.md b/docs/src/content/docs/faq.md index d84007b..88bc8a6 100644 --- a/docs/src/content/docs/faq.md +++ b/docs/src/content/docs/faq.md @@ -11,6 +11,10 @@ No. ColimaStack is a native macOS app for managing and observing Colima. Colima No. Install the Docker CLI separately. ColimaStack uses Docker commands to read containers, images, volumes, networks, stats, and disk usage from the selected Colima context. +## Do I need Docker or kubectl installed? + +Not for core Colima profile management. Install the Docker CLI only for Docker runtime inventory, and install `kubectl` only for Kubernetes inventory and context checks. + ## Can I use multiple Colima profiles? Yes. ColimaStack lists profiles and scopes operations through `COLIMA_PROFILE`. Docker context names are derived from the selected profile. diff --git a/docs/src/content/docs/features.md b/docs/src/content/docs/features.md index 22af5b7..5222eae 100644 --- a/docs/src/content/docs/features.md +++ b/docs/src/content/docs/features.md @@ -3,7 +3,7 @@ title: Features description: The main ColimaStack capabilities for local container and Kubernetes development. --- -ColimaStack is organized around the workflows developers repeat every day: check runtime health, start or stop a profile, inspect Docker resources, verify Kubernetes state, and recover from toolchain failures. +ColimaStack is organized around the workflows developers repeat every day: check runtime health, start or stop a profile, inspect Docker resources when the Docker CLI is available, verify Kubernetes state when `kubectl` is available, and recover from toolchain failures. ## Workspace overview @@ -15,7 +15,7 @@ Create, edit, start, stop, restart, update, and delete Colima profiles. Profile ## Docker resources -ColimaStack reads Docker resources through the Docker CLI for the active Colima context: +When the Docker CLI is installed, ColimaStack reads Docker resources through the active Colima context: - containers - images @@ -26,7 +26,7 @@ ColimaStack reads Docker resources through the Docker CLI for the active Colima ## Kubernetes resources -When Kubernetes is enabled for a profile, ColimaStack reads cluster state through `kubectl`: +When Kubernetes is enabled for a profile and `kubectl` is installed, ColimaStack reads cluster state through `kubectl`: - nodes - namespaces @@ -37,4 +37,4 @@ When Kubernetes is enabled for a profile, ColimaStack reads cluster state throug ## Diagnostics and recovery -The diagnostics workflow checks for required tools, Colima runtime status, Docker availability, and Kubernetes context. Errors are surfaced as actionable messages instead of raw command failures where possible. +The diagnostics workflow checks required and optional tools, Colima runtime status, Docker availability, and Kubernetes context. Errors are surfaced as actionable messages instead of raw command failures where possible. diff --git a/docs/src/content/docs/features/diagnostics.md b/docs/src/content/docs/features/diagnostics.md index 754473c..370a579 100644 --- a/docs/src/content/docs/features/diagnostics.md +++ b/docs/src/content/docs/features/diagnostics.md @@ -14,13 +14,13 @@ The app checks: - `kubectl` - `limactl` -Each check reports whether the tool is available, missing, or returned an error. +Each check reports whether the tool is available, missing, or returned an error. `colima` is required for core profile management. `docker`, `kubectl`, and `limactl` are optional checks that enable Docker inventory, Kubernetes inventory, and deeper runtime diagnostics. ## Runtime checks Colima status is read with `colima status --json` where possible. A stopped profile is treated as a normal state, not a fatal error. -Docker availability is checked against the expected Colima context so an unrelated active Docker context does not hide a local setup problem. +When the Docker CLI is installed, Docker availability is checked against the expected Colima context so an unrelated active Docker context does not hide a local setup problem. ## Kubernetes context diff --git a/docs/src/content/docs/index.md b/docs/src/content/docs/index.md index c23217a..4f938db 100644 --- a/docs/src/content/docs/index.md +++ b/docs/src/content/docs/index.md @@ -20,7 +20,7 @@ hero:
-ColimaStack is built for developers who already trust [Colima](https://github.com/abiosoft/colima) as their local container runtime and want a faster way to see, inspect, and recover their environment. It keeps the Colima CLI as the foundation, then adds a focused product layer for daily profile, Docker, and Kubernetes work. +ColimaStack is built for developers who already trust [Colima](https://github.com/abiosoft/colima) as their local container runtime and want a faster way to see, inspect, and recover their environment. It keeps the Colima CLI as the foundation, then adds optional Docker and Kubernetes visibility when those tools are installed.
@@ -38,15 +38,15 @@ ColimaStack is built for developers who already trust [Colima](https://github.co

Docker inventory

-

Browse containers, images, volumes, networks, stats, and disk usage for the active Colima context.

+

Browse containers, images, volumes, networks, stats, and disk usage for the active Colima context when the Docker CLI is installed.

Kubernetes awareness

-

Inspect nodes, namespaces, pods, deployments, services, and metrics when Kubernetes is enabled.

+

Inspect nodes, namespaces, pods, deployments, services, and metrics when Kubernetes is enabled and kubectl is installed.

Actionable diagnostics

-

Spot missing or misconfigured colima, docker, kubectl, and limactl tools before they derail the session.

+

Spot missing or misconfigured core and optional tools before they derail the workflow you are using.

diff --git a/docs/src/content/docs/install.md b/docs/src/content/docs/install.md index 85f46d6..f3fb863 100644 --- a/docs/src/content/docs/install.md +++ b/docs/src/content/docs/install.md @@ -3,36 +3,45 @@ title: Install description: Set up ColimaStack and the command-line tools it controls. --- -ColimaStack is a macOS app that controls local tools installed on your machine. It does not replace Colima, Docker, or kubectl. It makes those tools visible and easier to operate. +ColimaStack is a macOS app that controls local tools installed on your machine. It does not replace Colima, Docker, or kubectl. Colima is the core dependency; Docker CLI and kubectl are optional integrations for the workflows that use them. -## Requirements +## Core requirements - macOS - Colima -- Docker CLI + +## Optional integrations + +- Docker CLI for Docker runtime inventory - kubectl for Kubernetes workflows - Lima or `limactl` for deeper runtime diagnostics, normally installed by Homebrew with Colima ## Install dependencies -Install the standard Docker workflow toolchain with Homebrew: +Install the core Colima dependency with Homebrew: ```sh -brew install colima docker +brew install colima ``` -Install `kubectl` only if you plan to enable Kubernetes for a Colima profile: +Install optional tools only for the workflows you plan to use: ```sh +brew install docker brew install kubectl ``` -If ColimaStack diagnostics report that `limactl` is missing, install Lima explicitly with `brew install lima`. +The Docker CLI enables ColimaStack's Docker resource views for containers, images, volumes, networks, stats, and disk usage. `kubectl` enables Kubernetes inventory views. If ColimaStack diagnostics report that `limactl` is missing, install Lima explicitly with `brew install lima`. -Start a default Colima profile from Terminal if you want to verify the CLI path before opening the app: +Start a default Colima profile from Terminal if you want to verify the core CLI path before opening the app: ```sh colima start +``` + +If you installed the Docker CLI, verify the Docker context separately: + +```sh docker context use colima docker ps ``` diff --git a/docs/src/content/docs/kubernetes/overview.md b/docs/src/content/docs/kubernetes/overview.md index cbc5860..bc1ec8e 100644 --- a/docs/src/content/docs/kubernetes/overview.md +++ b/docs/src/content/docs/kubernetes/overview.md @@ -10,7 +10,7 @@ colima kubernetes start colima kubernetes stop ``` -The Kubernetes views use `kubectl` for cluster inventory. +The Kubernetes views use `kubectl` for cluster inventory. Install `kubectl` only if you want to use these views. ## Cluster view diff --git a/docs/src/content/docs/quick-start.md b/docs/src/content/docs/quick-start.md index 07d44c5..adf87cf 100644 --- a/docs/src/content/docs/quick-start.md +++ b/docs/src/content/docs/quick-start.md @@ -7,19 +7,19 @@ Use this guide to get from a clean macOS development machine to a visible Colima ## Prerequisites -Install Colima and the Docker CLI for the default Docker runtime: +Install Colima: ```sh -brew install colima docker +brew install colima ``` -Homebrew installs Lima as a Colima dependency. Install `kubectl` only if you plan to enable Kubernetes for a Colima profile: +Install the Docker CLI only if you want Docker resource views such as containers, images, volumes, networks, stats, and disk usage: ```sh -brew install kubectl +brew install docker ``` -If ColimaStack diagnostics report that `limactl` is missing, install Lima explicitly with `brew install lima`. +Homebrew installs Lima as a Colima dependency. Install `kubectl` only if you plan to enable Kubernetes for a Colima profile. If ColimaStack diagnostics report that `limactl` is missing, install Lima explicitly with `brew install lima`. ## Launch ColimaStack @@ -33,7 +33,7 @@ Open the ColimaStack macOS app. On first launch, the app runs diagnostics for: - Docker context availability - Kubernetes context availability -If a dependency is missing, open [Diagnostics](/features/diagnostics/) and follow the recovery suggestion. +Only `colima` is required for core profile management. Missing optional tools limit the related views: Docker CLI for Docker inventory, `kubectl` for Kubernetes inventory, and `limactl` for deeper runtime diagnostics. If a dependency is missing, open [Diagnostics](/features/diagnostics/) and follow the recovery suggestion for the workflow you want to use. ## Create or select a profile diff --git a/docs/src/content/docs/reference/command-api.md b/docs/src/content/docs/reference/command-api.md index 3236ed3..5872982 100644 --- a/docs/src/content/docs/reference/command-api.md +++ b/docs/src/content/docs/reference/command-api.md @@ -1,6 +1,6 @@ --- title: Command API -description: The Colima, Docker, and Kubernetes command contract used by ColimaStack. +description: The Colima command contract and optional Docker and Kubernetes read APIs used by ColimaStack. --- This page summarizes the app-owned command contract. The source reference is the repository document at `docs/colima-command-api-reference.md`. @@ -25,6 +25,8 @@ This page summarizes the app-owned command contract. The source reference is the ## Docker read APIs +These commands are used only when the Docker CLI is installed and the selected profile uses the Docker runtime. + | Screen | Command | | --- | --- | | Containers | `docker ps -a --format json` | @@ -36,6 +38,8 @@ This page summarizes the app-owned command contract. The source reference is the ## Kubernetes read APIs +These commands are used only when `kubectl` is installed and Kubernetes is enabled for the selected profile. + | Screen | Command | | --- | --- | | Cluster nodes | `kubectl get nodes -o json` | diff --git a/docs/src/content/docs/troubleshooting.md b/docs/src/content/docs/troubleshooting.md index a5802e7..60e38af 100644 --- a/docs/src/content/docs/troubleshooting.md +++ b/docs/src/content/docs/troubleshooting.md @@ -15,7 +15,7 @@ brew install colima ## Docker is unavailable -Verify the Docker CLI is installed and points at the expected context: +Docker CLI is optional. If you want Docker resource views, verify the Docker CLI is installed and points at the expected context: ```sh docker context ls @@ -27,7 +27,7 @@ For a named Colima profile, use `colima-`. ## Kubernetes is unavailable -Confirm Kubernetes is enabled for the selected profile: +kubectl is optional. If you want Kubernetes resource views, confirm Kubernetes is enabled for the selected profile: ```sh colima kubernetes start