Skip to content

feat(cli): support Podman in openshell doctor check #3694

Description

@politerealism

User Story

As an OpenShell user running the Podman compute driver, I want openshell doctor check to validate my Podman setup, so that I get the same actionable preflight diagnostics Docker users already get, instead of a check that always reports on Docker regardless of which driver I actually use.

Problem Statement

openshell doctor check (crates/openshell-cli/src/run.rs:215-251) unconditionally shells out to docker info to validate system prerequisites. It has no driver-detection logic and no Podman (or other compute driver) branch, so a user running the Podman driver gets a check that's irrelevant to their actual setup — it reports on Docker connectivity even when Docker isn't installed or in use, and it never validates the Podman socket, version, or rootless configuration the Podman driver actually depends on.

Impact / Why This Matters

Today, Podman users have no equivalent of doctor check to diagnose a broken Podman setup (missing socket, wrong Podman version, rootless misconfiguration) before running openshell. They're left with raw driver/gateway error messages or manual podman info inspection, instead of the single actionable pass/fail summary Docker users get. This is inconsistent with OpenShell's multi-driver design, where Podman is a fully supported, first-class compute driver, not a secondary one.

Proposed Design

openshell doctor check should detect which compute driver is configured (or accept an explicit override) and run the appropriate connectivity check: keep the existing docker info-based check for Docker, and add an equivalent check for Podman — verifying the Podman socket is reachable, reporting the Podman version, and validating rootless/rootful configuration analogous to what crates/openshell-driver-podman/src/driver.rs's own startup check already does inside the driver. The user-facing output format (labeled check line, "ok"/"FAILED" status, actionable guidance text) should stay consistent with the existing Docker check's style.

Acceptance Criteria

  • openshell doctor check validates Podman connectivity when the configured/detected driver is Podman, with output in the same style as the existing Docker check.
  • The check reports the Podman version on success, similar to Docker's --format {{.ServerVersion}}.
  • The check fails with an actionable error (naming the relevant socket path or environment variable) when Podman is unreachable, mirroring the existing DOCKER_HOST-mentioning guidance for Docker.
  • Existing Docker-only behavior is preserved for Docker users — this is additive, not a regression.

Alternatives Considered

Leave doctor check Docker-only and document it as such. Rejected because it leaves Podman users — a fully supported, first-class driver — without an equivalent preflight diagnostic tool, and the command's own framing ("system prerequisites," not "Docker prerequisites") implies broader driver coverage than it currently delivers.

Agent Investigation

Found while implementing #3663 (Podman CI coverage gaps). e2e/rust/tests/docker_preflight.rs tests exactly this Docker-only behavior end to end. doctor_check() in crates/openshell-cli/src/run.rs:215-251 unconditionally runs docker info --format {{.ServerVersion}} with no driver detection at all — confirmed by reading the function directly, not inferred. No Podman-equivalent CLI diagnostic exists. (A new e2e/rust/tests/podman_preflight.rs was added in PR #3690, but it tests a different thing: the Podman driver's behavior when its socket is unreachable, not the doctor check CLI command — it does not address this gap.)

Checklist

  • I've reviewed existing issues and the architecture docs
  • This is a design proposal, not a "please build this" request

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    state:acceptedA maintainer decided OpenShell should pursue this issue

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions