bug(rpm): allow gateway install on Docker hosts without requiring Podman #2007

Activity

1. pimlock commented on Jun 25, 2026

   

   pimlock

   on Jun 25, 2026

   CollaboratorAuthor

   More actions

   From @drew:

   Also need to update it so the gateway doesn't bind on 0.0.0.0
2. pimlock

   self-assigned this

   on Jun 25, 2026
3. pimlock commented on Jul 3, 2026

   

   pimlock

   on Jul 3, 2026

   Last edited by pimlock

   CollaboratorAuthor

   More actions

   🏗️ build-plan

   Implementation Plan

   Issue type: fix
   Complexity: Medium
   Confidence: High — the package path is clear; the bind-address change should be handled separately

   Summary

   Make the RPM and its user service runtime-neutral so installing openshell-gateway never pulls Podman onto a Docker host. Reuse the existing gateway runtime auto-detection instead of adding an installer-only runtime selector: fresh installs will select a reachable Podman socket when present, otherwise Docker when available.

   Make installer-triggered service failures visible at the top level. If the gateway cannot start because no runtime is usable, the installer will print service status and recent logs, explain how to install/start Docker or Podman or install and explicitly configure VM, and exit nonzero while leaving the installed packages in place.

   Keep the existing RPM 0.0.0.0:17670 bind override in this change. PR #1438 established that rootless Podman sandbox callbacks cannot use the loopback-only default; removing the all-interface bind safely requires a separate Podman networking design and live E2E coverage.

   Scope

   • openshell.spec: remove the base Recommends: podman and gateway Requires: podman, make package descriptions runtime-neutral, remove podman.socket ordering/wants, and preserve first-start config seeding.
   • deploy/rpm/gateway.toml.default: remove the explicit compute_drivers = ["podman"] pin so the gateway uses existing Kubernetes → Podman → Docker auto-detection; retain the current bind override for Podman compatibility.
   • crates/openshell-server/src/config_file.rs: update the RPM template contract test to require no pinned compute driver while retaining the expected bind address.
   • install.sh: guard Linux service enable/restart/active checks and Homebrew service restart; dump service status and recent journal/Homebrew logs before returning an actionable error. Remediation must distinguish installing/starting Docker or Podman from installing and explicitly configuring the VM driver.
   • tasks/scripts/test-install-sh.sh: cover failed service activation/restart paths, diagnostic collection, actionable runtime remediation text, and nonzero installer results after package installation.
   • .github/workflows/rpm-package.yml: verify built RPM metadata has no Podman requirement or recommendation and perform a DNF install transaction with Podman absent.
   • deploy/rpm/QUICKSTART.md, deploy/rpm/CONFIGURATION.md, and deploy/rpm/TROUBLESHOOTING.md: document runtime-neutral installation, Docker and Podman prerequisites, auto-detection, explicit overrides, upgrade behavior, no-runtime startup failure, and recovery.
   • docs/about/installation.mdx: add a package/runtime prerequisite matrix and explain which installers start services automatically or through install.sh.
   • docs/reference/sandbox-compute-drivers.mdx: document that DEB and Homebrew bundle openshell-driver-vm, RPM and Snap do not, separate release tarballs are available, and VM is never auto-detected.
   • docs/reference/gateway-config.mdx: align package-managed auto-detection and explicit VM-selection examples with the runtime-neutral RPM defaults.
   • crates/openshell-driver-vm/README.md: replace the stale RPM Podman-pinned description with the new auto-detection behavior and document separate VM artifact installation for RPM hosts.

   Implementation Steps

   1. Remove all RPM dependency and systemd-unit edges that cause DNF or systemd to pull/start Podman.
   2. Change the seeded RPM configuration to leave compute-driver selection unset so existing runtime auto-detection chooses the available local runtime.
   3. Make every installer-managed service startup failure dump platform-appropriate diagnostics and return an actionable, package-aware error without rolling back the installed package.
   4. Update the RPM config contract test, installer shell tests, and artifact-level package dependency/install assertions.
   5. Update packaged and published documentation with Docker/Podman prerequisites, service-start behavior, the VM inclusion matrix, separate RPM VM installation, no-runtime failure, and recovery paths.
   6. Run focused tests, mise run pre-commit, and the existing RPM/Podman validation path as applicable.

   Test Plan

   • Unit tests: Update rpm_default_config_parses_and_has_podman_defaults to assert the template parses, keeps the RPM bind address, and leaves compute_drivers unset. Extend tasks/scripts/test-install-sh.sh with mocked Linux and Homebrew service failures that assert diagnostics are emitted, remediation distinguishes available container runtimes from separately installed VM support, and the installer exits nonzero. Run existing compute-driver detection tests.
   • Integration tests: In the RPM build workflow, inspect Requires/Recommends, install the generated CLI and gateway RPMs with DNF in the clean Fedora build container, and assert Podman remains uninstalled.
   • E2E tests: Keep the existing Fedora RPM/Podman release canary as regression coverage. No E2E file change is planned; a Rocky 8 host with Docker CE remains the release-level reproduction target.

   Risks & Open Questions

   • Removing only the hard requirement is insufficient because DNF installs Recommends by default; both Podman dependency edges must be removed.
   • Existing user-owned ~/.config/openshell/gateway.toml files remain untouched on upgrade, so an existing Podman pin is preserved intentionally.
   • A direct RPM/DEB package transaction can succeed without a runtime. The higher-level install.sh intentionally exits nonzero if its post-install service verification fails; documentation must make clear that the package remains installed and can be recovered by installing/starting a runtime and restarting the service.
   • VM packaging differs by installer: DEB installs it under /usr/libexec/openshell, Homebrew installs it under the formula libexec, RPM and Snap do not include it, and matching standalone release tarballs are published. VM must always be selected explicitly with compute_drivers = ["vm"] or OPENSHELL_DRIVERS=vm.
   • On RPM hosts, VM remediation requires installing openshell-driver-vm under a configured driver_dir or a conventional path such as ~/.local/libexec/openshell, /usr/libexec/openshell, or /usr/local/libexec/openshell; configuration alone is insufficient.
   • Startup diagnostics must not claim that every failure is caused by a missing runtime. They should show the underlying logs first and present runtime setup as the common remediation for driver-selection failures.
   • Binding only to loopback is not included. The previous RPM regression fix documents that this breaks rootless Podman callbacks, so it should be tracked as a separate networking issue unless maintainers request a broader redesign.
   • No process identity, /proc, binary execution, SELinux, or AppArmor behavior changes are expected.

   Documentation Impact

   Update the RPM quickstart, configuration, and troubleshooting guides; general installation page; gateway configuration reference; compute-driver reference; and VM driver README. The docs will include a package/runtime prerequisite matrix, service-start behavior, VM inclusion and manual-install paths, explicit VM selection, and no-runtime recovery. No Helm or gateway TOML schema changes are expected.

   ---

   Revision 3 — document runtime prerequisites and VM packaging differences
   Revision 2 — add installer startup diagnostics and no-runtime recovery coverage
   Revision 1 — initial plan
4. pimlock

   added

   state:review-readyReady for human reviewReady for human review

   state:agent-readyApproved for agent implementationApproved for agent implementation

   state:in-progressWork is currently in progressWork is currently in progress

   and removed

   state:review-readyReady for human reviewReady for human review

   on Jul 3, 2026
5. pimlock commented on Jul 3, 2026

   

   pimlock

   on Jul 3, 2026

   CollaboratorAuthor

   More actions

   Implemented in #2137.

   The RPM no longer requires or recommends Podman and its user service no longer orders against podman.socket. Fresh RPM configs leave compute-driver selection unset so the gateway can select a reachable Podman socket or Docker. Installer-managed startup failures now print service diagnostics, explain that OpenShell remains installed, and provide Docker/Podman or explicitly configured VM recovery steps.

   The PR also adds RPM metadata/DNF transaction coverage, installer failure tests, the RPM config contract update, and documentation for runtime prerequisites and VM packaging across DEB, RPM, Homebrew, and Snap.

   The existing 0.0.0.0:17670 RPM bind override remains unchanged because rootless Podman callbacks require it; loopback binding should be tracked separately.

   Validation: mise run pre-commit, mise run test, and mise run ci all pass locally.
6. pimlock

   added

   state:pr-openedPR has been opened for this issuePR has been opened for this issue

   and removed

   state:agent-readyApproved for agent implementationApproved for agent implementation

   state:in-progressWork is currently in progressWork is currently in progress

   on Jul 3, 2026
7. github-actions commented on Jul 18, 2026

   

   github-actionsBot

   on Jul 18, 2026 – with GitHub Actions

   More actions

   This issue has had no activity for 14 days and is now marked stale. It may be closed in 7 days if there is no further activity. Comment or remove the state:stale label to keep it open.
8. github-actions

   added

   state:staleInactive item at risk of automatic closure.Inactive item at risk of automatic closure.

   on Jul 18, 2026
9. pimlock

   closed this as not plannedon Sep 28, 2026