Skip to content

Commit b52d683

Browse files
authored
Merge pull request #2 from maxamillion/openshell-podman
Openshell podman
2 parents 92b0b99 + d8908f8 commit b52d683

5 files changed

Lines changed: 309 additions & 0 deletions

File tree

‎INSTALL_PODMAN_MACOS.md‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
# Installing OpenShell with Podman on macOS (Apple Silicon)
2+
3+
Quick setup guide for running OpenShell with Podman on **macOS Apple Silicon (ARM64)**.
4+
5+
**Platform-specific**: This guide is for macOS only.
6+
7+
## Quick Start
8+
9+
```bash
10+
# 1. Install Podman and mise
11+
brew install podman mise
12+
13+
# 2. Run the automated setup script
14+
bash scripts/setup-podman-macos.sh
15+
16+
# 3. Set environment variables (follow the script's instructions)
17+
source ~/.zshrc # if you added them to your profile
18+
19+
# 4. Build cluster image
20+
mise run docker:build:cluster
21+
22+
# 5. Tag the image for local use
23+
podman tag localhost/openshell/cluster:dev ghcr.io/nvidia/openshell/cluster:dev
24+
25+
# 6. Build and install CLI
26+
cargo build --release -p openshell-cli
27+
mkdir -p ~/.local/bin
28+
cp target/release/openshell ~/.local/bin/
29+
30+
# 7. Create a sandbox
31+
openshell sandbox create
32+
```
33+
34+
## What Gets Installed
35+
36+
- **Podman**: Container runtime (Docker alternative)
37+
- **mise**: Task runner used by OpenShell project for build tasks
38+
39+
## What the Setup Script Does
40+
41+
`scripts/setup-podman-macos.sh` automates Podman machine configuration:
42+
43+
- Creates dedicated `openshell` Podman machine (8GB RAM, 4 CPUs)
44+
- Configures cgroup delegation (required for rootless k3s)
45+
- Sets up environment variables
46+
- Stops conflicting machines (only one can run at a time)
47+
- Optionally adds env vars to your shell profile
48+
49+
## Building Without mise
50+
51+
If you prefer not to use mise, run the build script directly:
52+
53+
```bash
54+
tasks/scripts/docker-build-image.sh cluster
55+
```
56+
57+
## Cleanup
58+
59+
```bash
60+
bash cleanup-openshell-podman-macos.sh
61+
```
62+
63+
## Troubleshooting
64+
65+
### Environment variables not set
66+
67+
```bash
68+
SOCKET=$(podman machine inspect openshell --format '{{.ConnectionInfo.PodmanSocket.Path}}')
69+
export CONTAINER_HOST="unix://${SOCKET}"
70+
export OPENSHELL_CONTAINER_RUNTIME=podman
71+
```
72+
73+
### "Gateway not reachable"
74+
75+
```bash
76+
openshell gateway destroy --name openshell
77+
openshell sandbox create
78+
```
79+
80+
### Build fails with memory errors
81+
82+
```bash
83+
podman machine stop openshell
84+
podman machine set openshell --memory 8192
85+
podman machine start openshell
86+
```
87+
88+
### "failed to find cpuset cgroup"
89+
90+
Verify cgroup delegation:
91+
92+
```bash
93+
podman machine ssh openshell "cat /etc/systemd/system/[email protected]/delegate.conf"
94+
```
95+
96+
Should show `Delegate=cpu cpuset io memory pids`. If not, run `scripts/setup-podman-macos.sh` again.

‎cleanup-openshell-podman-macos.sh‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
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+
# Cleanup script for OpenShell Podman installation on macOS
7+
# Removes all OpenShell containers, images, binaries, and configuration
8+
9+
set -e
10+
11+
echo "=== OpenShell Podman Cleanup Script ==="
12+
echo ""
13+
14+
# Destroy OpenShell gateway (if it exists)
15+
echo "Destroying OpenShell gateway..."
16+
if command -v openshell &>/dev/null; then
17+
openshell gateway destroy --name openshell 2>/dev/null || true
18+
fi
19+
20+
# Stop and remove any running OpenShell containers
21+
echo "Stopping OpenShell containers..."
22+
podman ps -a | grep openshell | awk '{print $1}' | xargs -r podman rm -f || true
23+
24+
# Remove OpenShell images
25+
echo "Removing OpenShell images..."
26+
podman images | grep -E "openshell|cluster" | awk '{print $3}' | xargs -r podman rmi -f || true
27+
28+
# Remove CLI binary
29+
echo "Removing CLI binary..."
30+
rm -f ~/.local/bin/openshell
31+
if [ -f /usr/local/bin/openshell ]; then
32+
echo "Removing /usr/local/bin/openshell (requires sudo)..."
33+
sudo rm -f /usr/local/bin/openshell
34+
fi
35+
36+
# Remove OpenShell configuration and data
37+
echo "Removing OpenShell configuration..."
38+
rm -rf ~/.openshell
39+
40+
# Remove build artifacts (from OpenShell directory)
41+
echo "Removing build artifacts..."
42+
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
43+
cd "$SCRIPT_DIR"
44+
rm -rf target/
45+
rm -rf deploy/docker/.build/
46+
47+
# Clean Podman cache
48+
echo "Cleaning Podman build cache..."
49+
podman system prune -af --volumes
50+
51+
echo ""
52+
echo "=== Cleanup Complete ==="
53+
echo ""
54+
echo "To completely remove the OpenShell Podman machine:"
55+
echo " podman machine stop openshell"
56+
echo " podman machine rm openshell"
57+
echo ""
58+
read -p "Do you want to remove the OpenShell Podman machine now? (y/N) " -n 1 -r
59+
echo
60+
if [[ $REPLY =~ ^[Yy]$ ]]; then
61+
echo "Stopping and removing OpenShell Podman machine..."
62+
podman machine stop openshell 2>/dev/null || true
63+
podman machine rm -f openshell 2>/dev/null || true
64+
echo "OpenShell Podman machine removed."
65+
else
66+
echo "Skipping Podman machine removal."
67+
echo "The machine is still available for future use."
68+
fi

‎deploy/docker/Dockerfile.images‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,10 @@ ARG SCCACHE_MEMCACHED_ENDPOINT
3333
# so cargo uses the Cargo.toml default (parallel codegen for fast linking).
3434
ARG CARGO_CODEGEN_UNITS
3535

36+
# Make build args available as environment variables
37+
ENV TARGETARCH=$TARGETARCH \
38+
BUILDARCH=$BUILDARCH
39+
3640
RUN apt-get update && apt-get install -y --no-install-recommends \
3741
cmake g++ make protobuf-compiler curl && rm -rf /var/lib/apt/lists/*
3842

‎scripts/setup-podman-macos.sh‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
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+
# Automated setup script for Podman on macOS
7+
# Handles Podman machine initialization, cgroup delegation, and environment setup
8+
9+
set -euo pipefail
10+
11+
MACHINE_NAME="${PODMAN_MACHINE_NAME:-openshell}"
12+
MEMORY="${PODMAN_MEMORY:-8192}"
13+
CPUS="${PODMAN_CPUS:-4}"
14+
15+
echo "=== OpenShell Podman Setup for macOS ==="
16+
echo ""
17+
18+
# Check if Podman is installed
19+
if ! command -v podman &>/dev/null; then
20+
echo "❌ Podman is not installed."
21+
echo ""
22+
echo "Install with: brew install podman"
23+
exit 1
24+
fi
25+
26+
echo "✓ Podman is installed ($(podman --version))"
27+
28+
# Check if machine already exists
29+
if podman machine list --format '{{.Name}}' | grep -q "^${MACHINE_NAME}$"; then
30+
echo ""
31+
echo "⚠️ Podman machine '${MACHINE_NAME}' already exists."
32+
read -p "Do you want to recreate it? This will delete the existing machine. (y/N) " -n 1 -r
33+
echo
34+
if [[ $REPLY =~ ^[Yy]$ ]]; then
35+
echo "Stopping and removing existing machine..."
36+
podman machine stop "${MACHINE_NAME}" 2>/dev/null || true
37+
podman machine rm -f "${MACHINE_NAME}"
38+
else
39+
echo "Using existing machine. Verifying configuration..."
40+
EXISTING=true
41+
fi
42+
fi
43+
44+
# Initialize machine if needed
45+
if [[ "${EXISTING:-false}" != "true" ]]; then
46+
echo ""
47+
echo "Initializing Podman machine '${MACHINE_NAME}' with ${MEMORY}MB RAM and ${CPUS} CPUs..."
48+
podman machine init "${MACHINE_NAME}" --memory "${MEMORY}" --cpus "${CPUS}"
49+
fi
50+
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
57+
echo " Stopping ${machine}..."
58+
podman machine stop "${machine}" 2>/dev/null || true
59+
fi
60+
fi
61+
done
62+
63+
# Start the machine
64+
echo ""
65+
echo "Starting Podman machine '${MACHINE_NAME}'..."
66+
if ! podman machine list --format '{{.Name}} {{.Running}}' | grep "^${MACHINE_NAME} " | grep -q "true"; then
67+
podman machine start "${MACHINE_NAME}"
68+
fi
69+
70+
# Set as default
71+
echo "Setting '${MACHINE_NAME}' as default connection..."
72+
podman system connection default "${MACHINE_NAME}"
73+
74+
# Configure cgroup delegation (CRITICAL for rootless k3s)
75+
echo ""
76+
echo "Configuring cgroup delegation for rootless k3s..."
77+
podman machine ssh "${MACHINE_NAME}" 'echo "[Service]
78+
Delegate=cpu cpuset io memory pids" | sudo tee /etc/systemd/system/[email protected]/delegate.conf' >/dev/null
79+
80+
podman machine ssh "${MACHINE_NAME}" "sudo systemctl daemon-reload"
81+
82+
# Restart for cgroup changes to take effect
83+
echo "Restarting machine for cgroup changes..."
84+
podman machine stop "${MACHINE_NAME}"
85+
podman machine start "${MACHINE_NAME}"
86+
87+
# Get socket path
88+
SOCKET_PATH=$(podman machine inspect "${MACHINE_NAME}" --format '{{.ConnectionInfo.PodmanSocket.Path}}')
89+
90+
echo ""
91+
echo "=== Setup Complete ==="
92+
echo ""
93+
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+
120+
echo ""
121+
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"
124+
echo " 3. Build CLI: cargo build --release -p openshell-cli"
125+
echo " 4. Install CLI: cp target/release/openshell ~/.local/bin/"

‎tasks/scripts/docker-build-image.sh‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -197,6 +197,21 @@ if [[ "${CONTAINER_RUNTIME}" == "podman" ]]; then
197197
# defaults to HTTPS and will fail. Pass --tls-verify=false in that case.
198198
podman_local_tls_args "${IMAGE_NAME:-}"
199199
TLS_ARGS=(${PODMAN_TLS_ARGS[@]+"${PODMAN_TLS_ARGS[@]}"})
200+
201+
# Podman doesn't auto-inject TARGETARCH/BUILDARCH like Docker buildx.
202+
# Detect host architecture and add as build args if not already present.
203+
ARCH_ARGS=()
204+
if ! printf '%s\n' "$@" | grep -q -- '--build-arg.*TARGETARCH'; then
205+
HOST_ARCH=$(uname -m)
206+
case "${HOST_ARCH}" in
207+
x86_64) TARGETARCH="amd64" ;;
208+
aarch64|arm64) TARGETARCH="arm64" ;;
209+
*) TARGETARCH="${HOST_ARCH}" ;;
210+
esac
211+
ARCH_ARGS+=(--build-arg "TARGETARCH=${TARGETARCH}")
212+
ARCH_ARGS+=(--build-arg "BUILDARCH=${TARGETARCH}")
213+
fi
214+
200215
# Filter OUTPUT_ARGS: Podman stores images locally by default (no --load)
201216
PODMAN_OUTPUT_ARGS=()
202217
for arg in ${OUTPUT_ARGS[@]+"${OUTPUT_ARGS[@]}"}; do
@@ -208,6 +223,7 @@ if [[ "${CONTAINER_RUNTIME}" == "podman" ]]; then
208223
podman build \
209224
--layers \
210225
"${COMMON_BUILD_ARGS[@]}" \
226+
${ARCH_ARGS[@]+"${ARCH_ARGS[@]}"} \
211227
${TLS_ARGS[@]+"${TLS_ARGS[@]}"} \
212228
${PODMAN_OUTPUT_ARGS[@]+"${PODMAN_OUTPUT_ARGS[@]}"} \
213229
.

0 commit comments

Comments
 (0)