feat(podman): improve macOS setup workflow and documentation#19
Merged
Merged
Conversation
- Add centralized environment configuration via scripts/podman.env - Auto-detects Podman machine socket path - Sets CONTAINER_HOST, OPENSHELL_CONTAINER_RUNTIME, registry vars - Simplifies local development setup - Make scripts/bin/openshell wrapper bash 3.2 compatible - Add read_lines_into_array() with version detection - Works with macOS default bash (3.2) without upgrade - Maintains bash 4+ performance with mapfile when available - Update scripts/setup-podman-macos.sh - Add user confirmation before stopping other machines - Update next steps output to reference new workflow - Update docs/get-started/install-podman-macos.md - Document complete workflow with mise run cluster:build:full - Add environment variable setup section - Clarify local registry usage for k3s cluster - Add note about debug CLI from mise build - Remove $ prompt symbols for easier copy/paste Tested end-to-end on macOS with Podman Machine. Cluster deploys successfully and CLI connects to gateway.
|
Caution Review failedFailed to post review comments 📝 WalkthroughWalkthroughThis pull request migrates the OpenShell project from NVIDIA to LobsterTrap stewardship, adds comprehensive container runtime abstraction to support both Docker and Podman, switches build infrastructure from custom self-hosted runners to GitHub-hosted runners, replaces NVIDIA base images with Hummingbird base images, and adds Podman setup documentation and utilities for Linux and macOS. Changes
Sequence Diagram(s)sequenceDiagram
participant User as User / CLI
participant CLI as openshell CLI
participant Runtime as Container Runtime<br/>(Docker or Podman)
participant Gateway as Gateway<br/>Container
participant K3s as K3s Cluster
User->>CLI: openshell gateway start
CLI->>CLI: detect_runtime()<br/>(OPENSHELL_CONTAINER_RUNTIME,<br/>probe sockets,<br/>check binaries)
CLI->>Runtime: check_runtime_available()
Runtime-->>CLI: version, daemon info
CLI->>Runtime: ensure_container<br/>(with runtime param)
Runtime->>Gateway: create container
Gateway->>K3s: bootstrap K3s
K3s-->>Gateway: ready
Gateway-->>Runtime: container healthy
Runtime-->>CLI: gateway running
CLI-->>User: Gateway ready at host:port
sequenceDiagram
participant Host as Host System
participant NS as Network Namespace
participant Sandbox as Sandbox Pod
participant Bridge as Pod Network Bridge
Host->>NS: detect namespace type
alt Named Namespace Available
NS->>NS: ip netns add openshell-xxx
NS->>NS: ip netns exec (setup veth)
else Fall back to Unshare
NS->>NS: spawn holder process<br/>with unshare(CLONE_NEWNET)
NS->>NS: nsenter -t pid -n<br/>(subsequent commands)
end
NS->>NS: configure iptables
NS->>Bridge: attach veth pair
Bridge->>Sandbox: enable pod connectivity
Sandbox-->>Host: network ready
Estimated code review effort🎯 4 (Complex) | ⏱️ ~50 minutes Poem
✨ Finishing Touches🧪 Generate unit tests (beta)
|
itdove
requested review from
cgwalters,
fatherlinux,
maxamillion,
openchow and
sallyom
as code owners
maxamillion
approved these changes
Apr 6, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR improves the Podman on macOS setup experience by adding centralized environment configuration, ensuring bash 3.2 compatibility, and enhancing documentation.
Related Issue
Fixes developer experience issues with Podman on macOS setup workflow.
Changes
Environment Configuration
scripts/podman.env: Centralized environment configuration that auto-detects Podman machine socket and sets all required variables (CONTAINER_HOST,OPENSHELL_CONTAINER_RUNTIME,OPENSHELL_REGISTRY,OPENSHELL_CLUSTER_IMAGE)Bash 3.2 Compatibility
scripts/bin/openshell: Addedread_lines_into_array()function with version detection to work with macOS default bash (3.2) while maintaining bash 4+ performance withmapfileSetup Script Improvements
scripts/setup-podman-macos.sh:source scripts/podman.envandmise run cluster:build:fullDocumentation Updates
docs/get-started/install-podman-macos.md:mise run cluster:build:fullscripts/podman.env$prompt symbols from all console blocks for easier copy/pasteTesting
Tested end-to-end on macOS (Apple Silicon) with Podman Machine:
scripts/podman.envmise run cluster:build:fullscripts/bin/openshellwrapper works with macOS bash 3.2Checklist
Summary by CodeRabbit
New Features
--container-runtimeflag and environment variablesDocumentation
Chores