Skip to content

feat: add macOS support to quickstart scripts #219

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
agullon wants to merge 2 commits into from
+122 −47
Closed

feat: add macOS support to quickstart scripts #219

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6a3f543
feat: add macOS support to quickstart.sh
agullon May 13, 2026
9d1b589
feat: make container name configurable via parameter
agullon May 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 6 additions & 4 deletions .github/actions/quick-start-clean/action.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,10 +52,12 @@ runs:
sudo podman image exists microshift-okd && exit 1

# Verify the LVM volume group and backing storage are removed
sudo vgs | grep myvg1 && exit 1
if [ -e /var/lib/microshift-okd ]; then
ls -la /var/lib/microshift-okd/
exit 1
if [ "$(uname -s)" != "Darwin" ]; then
sudo vgs | grep myvg1 && exit 1
if [ -e /var/lib/microshift-okd ]; then
ls -la /var/lib/microshift-okd/
exit 1
fi
fi

# Uncomment this to enable tmate-debug on failure
Expand Down
10 changes: 9 additions & 1 deletion .github/workflows/installers.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,12 +9,20 @@ jobs:
if: ${{ !github.event.pull_request.draft }}
strategy:
matrix:
runners: [ubuntu-24.04, ubuntu-24.04-arm]
runners: [ubuntu-24.04, ubuntu-24.04-arm, macos-latest]
runs-on: ${{ matrix.runners }}
steps:
- name: Check out MicroShift upstream repository
uses: actions/checkout@v4

- name: Install and configure podman (macOS)
if: runner.os == 'macOS'
run: |
brew install podman
podman machine init --memory 4096
podman machine set --rootful
podman machine start

# Test the quick Bootc image installation and clean procedures with the latest
# published build of the MicroShift container image.
- name: Run the quick Bootc image installation and clean scripts
Expand Down
59 changes: 38 additions & 21 deletions src/quickclean.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,28 +18,45 @@ if [ -n "${image_ref:-}" ]; then
podman rmi -f "${image_ref}" || true
fi

# Clean up the MicroShift data and uninstall RPMs
if rpm -q microshift &>/dev/null ; then
echo y | microshift-cleanup-data --all

# Remove the LVM configuration
if [ -f "${LVM_CONFIG}" ] ; then
rm -f "${LVM_CONFIG}"
systemctl daemon-reload
if [[ "$(uname -s)" == "Darwin" ]]; then
# macOS: clean up LVM inside the podman machine VM
MACHINE_SSH="podman machine ssh"
if [ -n "${SUDO_USER:-}" ]; then
MACHINE_SSH="sudo -u ${SUDO_USER} podman machine ssh"
fi
${MACHINE_SSH} "
if [ -f '${LVM_DISK}' ]; then
sudo lvremove -y '${VG_NAME}' || true
sudo vgremove -y '${VG_NAME}' || true
DEVICE_NAME=\$(sudo losetup -j '${LVM_DISK}' | cut -d: -f1)
[ -n \"\${DEVICE_NAME}\" ] && sudo losetup -d \${DEVICE_NAME}
sudo rm -rf '$(dirname "${LVM_DISK}")'
fi
" </dev/null
else
# Linux: clean up MicroShift data and uninstall RPMs
if rpm -q microshift &>/dev/null ; then
echo y | microshift-cleanup-data --all

dnf remove -y 'microshift*'
# Undo post-installation configuration
rm -f /etc/sysctl.d/99-microshift.conf
rm -f /root/.kube/config
fi
# Remove the LVM configuration
if [ -f "${LVM_CONFIG}" ] ; then
rm -f "${LVM_CONFIG}"
systemctl daemon-reload
fi

# Remove the LVM disk
if [ -f "${LVM_DISK}" ]; then
lvremove -y "${VG_NAME}" || true
vgremove -y "${VG_NAME}" || true
DEVICE_NAME="$(losetup -j "${LVM_DISK}" | cut -d: -f1)"
# shellcheck disable=SC2086
[ -n "${DEVICE_NAME}" ] && losetup -d ${DEVICE_NAME}
rm -rf "$(dirname "${LVM_DISK}")"
dnf remove -y 'microshift*'
# Undo post-installation configuration
rm -f /etc/sysctl.d/99-microshift.conf
rm -f /root/.kube/config
fi

# Remove the LVM disk
if [ -f "${LVM_DISK}" ]; then
lvremove -y "${VG_NAME}" || true
vgremove -y "${VG_NAME}" || true
DEVICE_NAME="$(losetup -j "${LVM_DISK}" | cut -d: -f1)"
# shellcheck disable=SC2086
[ -n "${DEVICE_NAME}" ] && losetup -d ${DEVICE_NAME}
rm -rf "$(dirname "${LVM_DISK}")"
fi
fi
90 changes: 69 additions & 21 deletions src/quickstart.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ REPO=${REPO:-microshift}
IMAGE=${IMAGE:-"ghcr.io/${OWNER}/${REPO}"}
TAG=${TAG:-latest}

CONTAINER_NAME="${1:-microshift-okd}"
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot May 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major | 🏗️ Heavy lift

Container name mismatch with cleanup script.

quickclean.sh hardcodes microshift-okd on line 15, so custom container names passed to this script won't be cleaned up.

🔧 Options to fix
  1. Pass the container name to quickclean.sh as an argument (requires updating both scripts and the workflow action)
  2. Use an environment variable to share the container name
  3. Remove the configurable container name feature if it's not needed
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/quickstart.sh` at line 9, The quickstart script defines a configurable
CONTAINER_NAME variable but quickclean.sh still hardcodes "microshift-okd", so
custom names won't be cleaned; fix by making quickclean.sh accept the container
name (e.g., read an argument $1 or environment variable) and update
quickstart.sh to either export CONTAINER_NAME before invoking quickclean.sh or
pass CONTAINER_NAME as the argument when calling quickclean.sh; specifically
change quickclean.sh to use the same symbol (CONTAINER_NAME) instead of the
literal and ensure quickstart.sh uses the same mechanism (export CONTAINER_NAME
or pass it) so both scripts reference the same container identifier.

LVM_DISK="/var/lib/microshift-okd/lvmdisk.image"
VG_NAME="myvg1"
PODMAN_VMAJOR=4
Expand All @@ -17,6 +18,8 @@ function check_prerequisites() {
echo "Install it with:"
if command -v dnf &>/dev/null; then
echo " sudo dnf install -y ${tool}"
elif command -v brew &>/dev/null; then
echo " brew install ${tool}"
elif command -v apt-get &>/dev/null; then
echo " sudo apt-get install -y ${tool}"
elif command -v zypper &>/dev/null; then
Expand Down Expand Up @@ -57,17 +60,41 @@ function prepare_lvm_disk() {
local -r lvm_disk="$1"
local -r vg_name="$2"

if [ -f "${lvm_disk}" ]; then
echo "INFO: '${lvm_disk}' already exists. Clearing and reusing it."
dd if=/dev/zero of="${lvm_disk}" bs=1M count=100 >/dev/null
return 0
fi
if [[ "$(uname -s)" == "Darwin" ]]; then
local lvm_dir machine_ssh
lvm_dir="$(dirname "${lvm_disk}")"
machine_ssh="podman machine ssh"
if [ "$(id -u)" -eq 0 ] && [ -n "${SUDO_USER:-}" ]; then
machine_ssh="sudo -u ${SUDO_USER} podman machine ssh"
fi
${machine_ssh} "
sudo mkdir -p '${lvm_dir}'
if [ -f '${lvm_disk}' ]; then
echo 'INFO: LVM disk already exists, reusing'
else
sudo truncate --size=1G '${lvm_disk}'
fi
if sudo vgs '${vg_name}' &>/dev/null; then
echo 'INFO: Volume group ${vg_name} already exists, reusing'
else
DEVICE=\$(sudo losetup --find --show --nooverlap '${lvm_disk}')
sudo vgcreate -f -y '${vg_name}' \"\${DEVICE}\"
echo 'INFO: Created volume group ${vg_name}'
fi
" </dev/null
else
if [ -f "${lvm_disk}" ]; then
echo "INFO: '${lvm_disk}' already exists. Clearing and reusing it."
dd if=/dev/zero of="${lvm_disk}" bs=1M count=100 >/dev/null
return 0
fi

mkdir -p "$(dirname "${lvm_disk}")"
truncate --size=1G "${lvm_disk}"
mkdir -p "$(dirname "${lvm_disk}")"
truncate --size=1G "${lvm_disk}"

local -r device_name="$(losetup --find --show --nooverlap "${lvm_disk}")"
vgcreate -f -y "${vg_name}" "${device_name}"
local -r device_name="$(losetup --find --show --nooverlap "${lvm_disk}")"
vgcreate -f -y "${vg_name}" "${device_name}"
fi
}

function run_bootc_image() {
Expand All @@ -93,7 +120,7 @@ function run_bootc_image() {
podman run --privileged --rm -d \
--replace \
${vol_opts} \
--name microshift-okd \
--name "${CONTAINER_NAME}" \
--hostname 127.0.0.1.nip.io \
"${image_ref}"

Expand All @@ -102,7 +129,7 @@ function run_bootc_image() {
local -r max_wait=300
local waited=0
while [ "${waited}" -lt "${max_wait}" ] ; do
if podman exec microshift-okd /bin/test -f "${kubeconfig}" &>/dev/null ; then
if podman exec "${CONTAINER_NAME}" /bin/test -f "${kubeconfig}" &>/dev/null ; then
break
fi
sleep 1
Expand All @@ -112,15 +139,15 @@ function run_bootc_image() {
echo "ERROR: Timed out waiting for MicroShift to start after ${max_wait}s"
echo
echo "Stopping the container..."
podman stop microshift-okd &>/dev/null || true
podman stop "${CONTAINER_NAME}" &>/dev/null || true
exit 1
fi

# Verify that DNS resolution works inside the container.
# VPN connections or custom DNS configurations on the host may
# prevent the container from resolving external hostnames, causing
# pods to stay in ContainerCreating while image pulls time out.
if ! podman exec microshift-okd getent hosts quay.io &>/dev/null ; then
if ! podman exec "${CONTAINER_NAME}" getent hosts quay.io &>/dev/null ; then
echo
echo "ERROR: DNS resolution for 'quay.io' failed inside the container."
echo "MicroShift pods will not be able to pull container images."
Expand All @@ -130,15 +157,36 @@ function run_bootc_image() {
echo "Consider disconnecting from VPN or configuring DNS manually."
echo
echo "Stopping the container..."
podman stop microshift-okd &>/dev/null || true
podman stop "${CONTAINER_NAME}" &>/dev/null || true
exit 1
fi
}

# Check if the script is running as root
if [ "$(id -u)" -ne 0 ]; then
echo "ERROR: This script must be run as root (use sudo)"
exit 1
# Platform-specific initialization
if [[ "$(uname -s)" == "Darwin" ]]; then
if ! podman info &>/dev/null </dev/null; then
echo "ERROR: Cannot connect to podman."
echo "Set up a podman machine with rootful mode:"
echo " podman machine init --memory 4096"
echo " podman machine set --rootful"
echo " podman machine start"
exit 1
fi

if [ "$(id -u)" -ne 0 ]; then
local_rootful="$(podman machine inspect --format '{{.Rootful}}' 2>/dev/null || echo "false")"
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot May 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Missing local declaration.

The variable name suggests local scope but it's not declared with the local keyword.

🔧 Proposed fix 
-    local_rootful="$(podman machine inspect --format '{{.Rootful}}' 2>/dev/null || echo "false")"
+    local local_rootful
+    local_rootful="$(podman machine inspect --format '{{.Rootful}}' 2>/dev/null || echo "false")"
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
local_rootful="$(podman machine inspect --format '{{.Rootful}}' 2>/dev/null || echo "false")"
local local_rootful
local_rootful="$(podman machine inspect --format '{{.Rootful}}' 2>/dev/null || echo "false")"
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/quickstart.sh` at line 177, The variable local_rootful is intended to be
function-scoped but is declared without the local keyword; update the assignment
to declare it as a local variable (e.g., use local local_rootful when assigning
the result of podman machine inspect --format '{{.Rootful}}' 2>/dev/null || echo
"false") so it doesn't leak into the global environment; locate the assignment
of local_rootful in src/quickstart.sh and prepend the local keyword to the
variable declaration.

if [[ "${local_rootful}" != "true" ]]; then
echo "ERROR: Podman machine must be in rootful mode (required for MicroShift)."
echo " podman machine stop && podman machine set --rootful && podman machine start"
exit 1
fi
fi
else
# Linux: must run as root
if [ "$(id -u)" -ne 0 ]; then
echo "ERROR: This script must be run as root (use sudo)"
exit 1
fi
fi

check_prerequisites podman
Expand All @@ -163,15 +211,15 @@ run_bootc_image "${IMAGE}:${TAG}"
echo
echo "MicroShift is running in a bootc container"
echo "Hostname: 127.0.0.1.nip.io"
echo "Container: microshift-okd"
echo "Container: ${CONTAINER_NAME}"
echo "LVM disk: ${LVM_DISK}"
echo "VG name: ${VG_NAME}"
echo
echo "To access the container, run the following command:"
echo " - sudo podman exec -it microshift-okd /bin/bash -l"
echo " - sudo podman exec -it ${CONTAINER_NAME} /bin/bash -l"
echo
echo "To verify that MicroShift pods are up and running, run the following command:"
echo " - sudo podman exec -it microshift-okd kubectl get pods -A"
echo " - sudo podman exec -it ${CONTAINER_NAME} kubectl get pods -A"
Comment on lines +219 to +222
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot May 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick win

Instructions should be platform-aware.

On macOS, when not running as root, users don't need sudo for podman commands. The Darwin initialization (lines 166-183) allows non-root execution, but these instructions always show sudo.

🔧 Suggested approach

Conditionally emit instructions based on platform and execution context:

if [[ "$(uname -s)" == "Darwin" ]] && [ "$(id -u)" -ne 0 ]; then
    EXEC_PREFIX=""
else
    EXEC_PREFIX="sudo "
fi

echo "To access the container, run the following command:"
echo " - ${EXEC_PREFIX}podman exec -it ${CONTAINER_NAME} /bin/bash -l"
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/quickstart.sh` around lines 219 - 222, Make the displayed podman commands
platform-aware by introducing an EXEC_PREFIX determined from uname and uid
(e.g., if uname -s == "Darwin" and id -u != 0 then EXEC_PREFIX="" else
EXEC_PREFIX="sudo "), then use that EXEC_PREFIX variable when emitting the
podman/kubectl examples (replace the hardcoded "sudo " in the lines that echo
the podman exec and kubectl get pods commands), referencing the existing
CONTAINER_NAME variable so outputs become "${EXEC_PREFIX}podman exec -it
${CONTAINER_NAME} /bin/bash -l" and "${EXEC_PREFIX}podman exec -it
${CONTAINER_NAME} kubectl get pods -A".

echo
echo "To uninstall MicroShift, run the following command:"
echo " - curl -s https://${OWNER}.github.io/${REPO}/quickclean.sh | sudo bash"
Loading