Skip to content

Commit 8781e68

Browse files
authored
Merge pull request NVIDIA#19 from itdove/podman-env-improvements
feat(podman): improve macOS setup workflow and documentation
2 parents 18188bb + 91290fa commit 8781e68

4 files changed

Lines changed: 143 additions & 76 deletions

File tree

‎docs/get-started/install-podman-macos.md‎

Lines changed: 57 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -31,23 +31,22 @@ This guide walks through installing and configuring Podman on macOS (Apple Silic
3131
## Quick Start
3232

3333
```console
34-
$ brew install podman mise
35-
$ bash scripts/setup-podman-macos.sh
36-
$ source ~/.zshrc
37-
$ mise run docker:build:cluster
38-
$ podman tag localhost/openshell/cluster:dev ghcr.io/lobstertrap/openshell/cluster:dev
39-
$ cargo build --release -p openshell-cli
40-
$ mkdir -p ~/.local/bin
41-
$ cp target/release/openshell ~/.local/bin/
42-
$ openshell sandbox create
34+
brew install podman mise
35+
bash scripts/setup-podman-macos.sh
36+
source scripts/podman.env
37+
mise run cluster:build:full
38+
cargo build --release -p openshell-cli
39+
mkdir -p ~/.local/bin
40+
cp target/release/openshell ~/.local/bin/
41+
openshell sandbox create
4342
```
4443

4544
## Install Podman and mise
4645

4746
Install Podman (container runtime) and mise (task runner used by the OpenShell project):
4847

4948
```console
50-
$ brew install podman mise
49+
brew install podman mise
5150
```
5251

5352
## Run the Automated Setup Script
@@ -56,99 +55,119 @@ The `scripts/setup-podman-macos.sh` script automates Podman Machine configuratio
5655

5756
- Creates a dedicated `openshell` Podman machine (8 GB RAM, 4 CPUs)
5857
- Configures cgroup delegation (required for the embedded k3s cluster)
59-
- Sets up environment variables
60-
- Stops conflicting machines (only one can run at a time)
61-
- Optionally adds environment variables to your shell profile
58+
- Stops conflicting machines (only one can run at a time, with user confirmation)
6259

6360
```console
64-
$ bash scripts/setup-podman-macos.sh
61+
bash scripts/setup-podman-macos.sh
6562
```
6663

67-
Follow the script's instructions to set environment variables. If you chose to add them to your shell profile:
64+
## Set Up Environment Variables
65+
66+
Source the `scripts/podman.env` file to configure your shell for local development:
6867

6968
```console
70-
$ source ~/.zshrc
69+
source scripts/podman.env
7170
```
7271

73-
## Build the Cluster Image
72+
This sets:
73+
- `CONTAINER_HOST` - Podman socket path
74+
- `OPENSHELL_CONTAINER_RUNTIME=podman` - Use Podman runtime
75+
- `OPENSHELL_REGISTRY=127.0.0.1:5000/openshell` - Local registry for component images
76+
- `OPENSHELL_CLUSTER_IMAGE=localhost/openshell/cluster:dev` - Local cluster image
7477

75-
Using mise:
78+
To make these persistent, add to your shell profile (`~/.zshrc` or `~/.bashrc`):
7679

7780
```console
78-
$ mise run docker:build:cluster
81+
echo "source $(pwd)/scripts/podman.env" >> ~/.zshrc
7982
```
8083

81-
Or directly without mise:
84+
## Build and Deploy the Cluster
85+
86+
Build images, set up the local registry, and deploy the k3s cluster:
8287

8388
```console
84-
$ tasks/scripts/docker-build-image.sh cluster
89+
mise run cluster:build:full
8590
```
8691

87-
Tag the image for local use:
92+
This command:
93+
- Builds the gateway image
94+
- Starts a local container registry at `127.0.0.1:5000`
95+
- Builds the cluster image
96+
- Pushes images to the local registry
97+
- Bootstraps a k3s cluster inside a Podman container
98+
- Deploys the OpenShell gateway
99+
100+
Or run the script directly:
88101

89102
```console
90-
$ podman tag localhost/openshell/cluster:dev ghcr.io/lobstertrap/openshell/cluster:dev
103+
tasks/scripts/cluster-bootstrap.sh build
91104
```
92105

93106
## Build and Install the CLI
94107

108+
**Note:** If you ran `mise run cluster:build:full` above, a debug version of the CLI was automatically compiled. You can use it directly from the project directory without installing:
109+
110+
```console
111+
./target/debug/openshell --version
112+
```
113+
114+
For a release-optimized binary that works system-wide:
115+
95116
```console
96-
$ cargo build --release -p openshell-cli
97-
$ mkdir -p ~/.local/bin
98-
$ cp target/release/openshell ~/.local/bin/
117+
cargo build --release -p openshell-cli
118+
mkdir -p ~/.local/bin
119+
cp target/release/openshell ~/.local/bin/
99120
```
100121

101122
## Create a Sandbox
102123

103124
```console
104-
$ openshell sandbox create
125+
openshell sandbox create
105126
```
106127

107128
## Cleanup
108129

109130
To remove all OpenShell resources and optionally the Podman machine:
110131

111132
```console
112-
$ bash cleanup-openshell-podman-macos.sh
133+
bash cleanup-openshell-podman-macos.sh
113134
```
114135

115136
## Troubleshooting
116137

117138
### Environment variables not set
118139

119-
If OpenShell cannot find the Podman socket, set the environment variables manually:
140+
If OpenShell cannot find the Podman socket, source the environment file:
120141

121142
```console
122-
$ SOCKET=$(podman machine inspect openshell --format '{{.ConnectionInfo.PodmanSocket.Path}}')
123-
$ export CONTAINER_HOST="unix://${SOCKET}"
124-
$ export OPENSHELL_CONTAINER_RUNTIME=podman
143+
source scripts/podman.env
125144
```
126145

127146
### "Gateway not reachable"
128147

129148
Destroy the existing gateway and recreate:
130149

131150
```console
132-
$ openshell gateway destroy --name openshell
133-
$ openshell sandbox create
151+
openshell gateway destroy --name openshell
152+
openshell sandbox create
134153
```
135154

136155
### Build fails with memory errors
137156

138157
Increase the Podman machine memory allocation:
139158

140159
```console
141-
$ podman machine stop openshell
142-
$ podman machine set openshell --memory 8192
143-
$ podman machine start openshell
160+
podman machine stop openshell
161+
podman machine set openshell --memory 8192
162+
podman machine start openshell
144163
```
145164

146165
### "failed to find cpuset cgroup"
147166

148167
Verify cgroup delegation inside the Podman machine:
149168

150169
```console
151-
$ podman machine ssh openshell "cat /etc/systemd/system/[email protected]/delegate.conf"
170+
podman machine ssh openshell "cat /etc/systemd/system/[email protected]/delegate.conf"
152171
```
153172

154173
The output should show `Delegate=cpu cpuset io memory pids`. If not, run `scripts/setup-podman-macos.sh` again.

‎scripts/bin/openshell‎

Lines changed: 23 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,27 @@ PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
66
BINARY="$PROJECT_ROOT/target/debug/openshell"
77
STATE_FILE="$PROJECT_ROOT/.cache/openshell-build.state"
88

9+
# ---------------------------------------------------------------------------
10+
# Bash version compatibility helper
11+
# ---------------------------------------------------------------------------
12+
13+
# Read lines into an array variable (bash 3 & 4 compatible)
14+
# Usage: read_lines_into_array array_name < <(command)
15+
read_lines_into_array() {
16+
local array_name=$1
17+
if ((BASH_VERSINFO[0] >= 4)); then
18+
# Bash 4+: use mapfile (faster)
19+
mapfile -t "$array_name"
20+
else
21+
# Bash 3: use while loop
22+
local line
23+
eval "$array_name=()"
24+
while IFS= read -r line; do
25+
eval "$array_name+=(\"\$line\")"
26+
done
27+
fi
28+
}
29+
930
# ---------------------------------------------------------------------------
1031
# Fingerprint-based rebuild check
1132
#
@@ -26,7 +47,7 @@ else
2647
current_head=$(git rev-parse HEAD 2>/dev/null || echo "unknown")
2748

2849
# Collect dirty (modified, staged, untracked) files
29-
mapfile -t changed_files < <(
50+
read_lines_into_array changed_files < <(
3051
{
3152
git diff --name-only 2>/dev/null
3253
git diff --name-only --cached 2>/dev/null
@@ -95,7 +116,7 @@ if [[ "$needs_build" == "1" ]]; then
95116
cd "$PROJECT_ROOT"
96117
new_head=$(git rev-parse HEAD 2>/dev/null || echo "unknown")
97118
# Recompute fingerprint of remaining dirty files (build may not change them)
98-
mapfile -t post_files < <(
119+
read_lines_into_array post_files < <(
99120
{
100121
git diff --name-only 2>/dev/null
101122
git diff --name-only --cached 2>/dev/null

‎scripts/podman.env‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
#!/usr/bin/env bash
2+
3+
# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
4+
# SPDX-License-Identifier: Apache-2.0
5+
6+
# Podman environment setup for OpenShell development on macOS
7+
# Usage: source scripts/podman.env
8+
9+
MACHINE_NAME="${PODMAN_MACHINE_NAME:-openshell}"
10+
11+
# Get Podman socket path from the machine
12+
if command -v podman &>/dev/null; then
13+
SOCKET_PATH=$(podman machine inspect "${MACHINE_NAME}" --format '{{.ConnectionInfo.PodmanSocket.Path}}' 2>/dev/null)
14+
15+
if [ -z "${SOCKET_PATH}" ]; then
16+
echo "⚠️ Warning: Podman machine '${MACHINE_NAME}' not found or not configured" >&2
17+
echo " Run: bash scripts/setup-podman-macos.sh" >&2
18+
else
19+
# Container runtime configuration
20+
export CONTAINER_HOST="unix://${SOCKET_PATH}"
21+
export OPENSHELL_CONTAINER_RUNTIME=podman
22+
23+
# Local development image registry
24+
export OPENSHELL_REGISTRY="127.0.0.1:5000/openshell"
25+
export OPENSHELL_CLUSTER_IMAGE="localhost/openshell/cluster:dev"
26+
27+
echo "✓ Podman environment configured:"
28+
echo " CONTAINER_HOST=${CONTAINER_HOST}"
29+
echo " OPENSHELL_CONTAINER_RUNTIME=${OPENSHELL_CONTAINER_RUNTIME}"
30+
echo " OPENSHELL_REGISTRY=${OPENSHELL_REGISTRY}"
31+
echo " OPENSHELL_CLUSTER_IMAGE=${OPENSHELL_CLUSTER_IMAGE}"
32+
fi
33+
else
34+
echo "❌ Error: Podman is not installed" >&2
35+
echo " Install with: brew install podman" >&2
36+
fi

‎scripts/setup-podman-macos.sh‎

Lines changed: 27 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -48,17 +48,31 @@ if [[ "${EXISTING:-false}" != "true" ]]; then
4848
podman machine init "${MACHINE_NAME}" --memory "${MEMORY}" --cpus "${CPUS}"
4949
fi
5050

51-
# Stop any other running machines
52-
echo ""
53-
echo "Stopping other Podman machines (only one can run at a time)..."
54-
for machine in $(podman machine list --format '{{.Name}}' --noheading); do
55-
if [[ "$machine" != "${MACHINE_NAME}" ]]; then
56-
if podman machine list --format '{{.Name}} {{.Running}}' | grep "^${machine} " | grep -q "true"; then
51+
# Check for other running machines
52+
RUNNING_MACHINES=$(podman machine list --format '{{.Name}} {{.Running}}' | grep -v "^${MACHINE_NAME} " | grep "true" | awk '{print $1}' || true)
53+
54+
if [ -n "${RUNNING_MACHINES}" ]; then
55+
echo ""
56+
echo "⚠️ Other Podman machines are currently running:"
57+
echo "${RUNNING_MACHINES}" | while read -r machine; do
58+
echo " - ${machine}"
59+
done
60+
echo ""
61+
echo "Only one Podman machine can run at a time."
62+
read -p "Stop these machines to continue? (y/N) " -n 1 -r
63+
echo
64+
if [[ $REPLY =~ ^[Yy]$ ]]; then
65+
echo "Stopping other Podman machines..."
66+
echo "${RUNNING_MACHINES}" | while read -r machine; do
5767
echo " Stopping ${machine}..."
5868
podman machine stop "${machine}" 2>/dev/null || true
59-
fi
69+
done
70+
else
71+
echo "Cannot start '${MACHINE_NAME}' while other machines are running."
72+
echo "Please stop them manually and run this script again."
73+
exit 1
6074
fi
61-
done
75+
fi
6276

6377
# Start the machine
6478
echo ""
@@ -91,35 +105,12 @@ echo ""
91105
echo "=== Setup Complete ==="
92106
echo ""
93107
echo "Podman machine '${MACHINE_NAME}' is ready!"
94-
echo ""
95-
echo "Environment variables (add to your shell profile):"
96-
echo " export CONTAINER_HOST=\"unix://${SOCKET_PATH}\""
97-
echo " export OPENSHELL_CONTAINER_RUNTIME=podman"
98-
echo ""
99-
echo "To set them now, run:"
100-
echo " export CONTAINER_HOST=\"unix://${SOCKET_PATH}\""
101-
echo " export OPENSHELL_CONTAINER_RUNTIME=podman"
102-
echo ""
103-
104-
# Offer to add to shell profile
105-
read -p "Add environment variables to ~/.zshrc? (y/N) " -n 1 -r
106-
echo
107-
if [[ $REPLY =~ ^[Yy]$ ]]; then
108-
if ! grep -q "CONTAINER_HOST.*${MACHINE_NAME}" ~/.zshrc 2>/dev/null; then
109-
echo "" >> ~/.zshrc
110-
echo "# OpenShell Podman environment" >> ~/.zshrc
111-
echo "export CONTAINER_HOST=\"unix://${SOCKET_PATH}\"" >> ~/.zshrc
112-
echo "export OPENSHELL_CONTAINER_RUNTIME=podman" >> ~/.zshrc
113-
echo "✓ Added to ~/.zshrc"
114-
echo " Run: source ~/.zshrc"
115-
else
116-
echo "⚠️ Environment variables already in ~/.zshrc"
117-
fi
118-
fi
119-
120108
echo ""
121109
echo "Next steps:"
122-
echo " 1. Source your shell profile or set environment variables"
123-
echo " 2. Build cluster image: mise run docker:build:cluster"
110+
echo " 1. Set up environment: source scripts/podman.env"
111+
echo " 2. Build and deploy: mise run cluster:build:full"
124112
echo " 3. Build CLI: cargo build --release -p openshell-cli"
125113
echo " 4. Install CLI: cp target/release/openshell ~/.local/bin/"
114+
echo ""
115+
echo "To make the environment persistent, add to your shell profile (~/.zshrc):"
116+
echo " source $(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/scripts/podman.env"

0 commit comments

Comments
 (0)