Skip to content

Commit e15b8bf

Browse files
committed
feat(install): improve snapd detection and clarify docs around snap selection
Signed-off-by: Oliver Calder <oliver.calder@canonical.com>
1 parent d69af11 commit e15b8bf

5 files changed

Lines changed: 100 additions & 38 deletions

File tree

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,8 @@ See [Architecture](https://docs.nvidia.com/openshell/latest/about/architecture)
3131

3232
You need Linux, macOS on Apple Silicon, or Windows with WSL 2 (experimental), plus Docker, Podman, or host virtualization. See the [Support Matrix](https://docs.nvidia.com/openshell/latest/about/support-matrix) for details.
3333

34+
On Linux with snapd, the default installation requires Docker Engine from a system package or Docker's repository; the Docker snap is unsupported. If you have snapd installed but want to use Podman or VMs instead of Docker, or you prefer a [native package](https://docs.nvidia.com/openshell/latest/about/installation#linux), you may do so with `OPENSHELL_INSTALL_METHOD=deb` or `rpm`.
35+
3436
```shell
3537
curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh
3638
openshell sandbox create --name demo

‎crates/openshell-driver-vm/README.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -311,17 +311,17 @@ create TAP devices or install nftables/iptables rules.
311311
`release-vm-kernel.yml`
312312
313313
On Debian-family Linux amd64 and arm64 systems, `install.sh` installs the
314-
Debian package when the `snap` command is unavailable, automatic selection
315-
receives an exact `OPENSHELL_VERSION` release tag, or
314+
Debian package when snapd is unavailable, `OPENSHELL_VERSION=pre` or an exact
315+
release tag is requested, or
316316
`OPENSHELL_INSTALL_METHOD=deb` is set. That package includes
317317
`openshell-gateway` and `openshell-driver-vm`, but leaves
318318
`OPENSHELL_COMPUTE_DRIVER` unset so the gateway uses its normal runtime
319319
auto-detection. Set `OPENSHELL_COMPUTE_DRIVER=vm` to force the VM driver.
320320
321321
On RPM-family Linux x86_64 and aarch64 systems, the equivalent native path
322322
installs the `openshell` and `openshell-gateway` RPM packages from the selected
323-
release tag. Select it explicitly with `OPENSHELL_INSTALL_METHOD=rpm`. The RPM
324-
gateway package is configured for the Podman driver.
323+
release tag. It is selected automatically under the same conditions or with
324+
`OPENSHELL_INSTALL_METHOD=rpm`. The RPM gateway package uses the Podman driver.
325325
326326
On Apple Silicon macOS, `install.sh` stages the generated `openshell.rb`
327327
formula from the selected release in the `nvidia/openshell` Homebrew tap.

‎docs/about/installation.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -86,7 +86,7 @@ The gateway reads `~/.config/openshell/gateway.toml` if it exists, otherwise the
8686

8787
## Linux
8888

89-
When the `snap` command is available, the script installs the [snap](#snap) package for the latest stable release or the rolling `dev` release. Otherwise, it installs a Debian package on Debian and Ubuntu or RPM packages on Fedora and RHEL. During automatic selection, prereleases and explicit release tags use native packages so the installer can select the exact release artifacts. Explicit `OPENSHELL_INSTALL_METHOD=snap` supports only an unset version or `OPENSHELL_VERSION=dev`.
89+
When snapd is available, the script installs the [snap](#snap) package for the latest stable release or the rolling `dev` release. Otherwise, it installs a Debian package on Debian and Ubuntu or RPM packages on Fedora and RHEL. Prereleases and explicit release tags use native packages. Explicit `OPENSHELL_INSTALL_METHOD=snap` supports only an unset version or `OPENSHELL_VERSION=dev`.
9090

9191
Set `OPENSHELL_INSTALL_METHOD=deb` or `OPENSHELL_INSTALL_METHOD=rpm` to select a native package explicitly. Native Linux packages require glibc 2.28 or newer.
9292

@@ -123,7 +123,7 @@ sudo loginctl enable-linger $USER
123123

124124
The snap requires Docker Engine installed from your distribution or Docker's package repository. The Docker snap is not compatible. To use Podman or the VM driver instead, select a native package with `OPENSHELL_INSTALL_METHOD=deb` or `OPENSHELL_INSTALL_METHOD=rpm`.
125125

126-
The snap does not migrate existing Debian, RPM, or Homebrew installs. If the script detects an existing native installation while selecting the snap, it stops before making changes. To update the existing native installation instead, rerun it with `OPENSHELL_INSTALL_METHOD=deb` or `OPENSHELL_INSTALL_METHOD=rpm`. To migrate, remove the existing installation after backing up any state you need, then rerun the script with `OPENSHELL_ACK_BREAKING_UPGRADE=1`, or install the snap directly:
126+
The snap does not migrate existing Debian, RPM, or Homebrew installs. If the script detects an existing native installation while selecting the snap, it stops before making changes. To keep the native installation, rerun it with `OPENSHELL_INSTALL_METHOD=deb` or `OPENSHELL_INSTALL_METHOD=rpm`. To migrate, back up any state you need, remove the native installation, and rerun the script. Set `OPENSHELL_ACK_BREAKING_UPGRADE=1` only if a detected native `openshell` binary remains after cleanup. You can also install the snap directly:
127127

128128
```shell
129129
sudo snap install openshell

‎install.sh‎

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
#
55
# Install OpenShell from a GitHub release.
66
#
7-
# Linux automatically installs the snap when the snap command is available and
7+
# Linux automatically installs the snap when snapd is available and
88
# the version is unset or dev; exact releases and prereleases use native packages.
99
# Apple Silicon macOS installs the generated Homebrew formula, so Homebrew owns
1010
# the binary layout and launchd service lifecycle.
@@ -64,13 +64,13 @@ ENVIRONMENT VARIABLES:
6464
pre-v0.0.37 or non-snap installation.
6565
OPENSHELL_INSTALL_METHOD
6666
Linux package to install: snap, deb, or rpm. Unset
67-
selects snap when available, otherwise deb or rpm.
67+
selects snap when snapd is available, otherwise deb or rpm.
6868
6969
NOTES:
7070
When OPENSHELL_VERSION is unset, this resolves the latest tagged release
7171
from ${GITHUB_URL}/releases/latest.
7272
73-
Linux installs the OpenShell snap when the snap command is available and
73+
Linux installs the OpenShell snap when snapd is available and
7474
OPENSHELL_VERSION is unset or dev. Snap installs use latest/stable by
7575
default and latest/edge for dev. Explicit release tags and prereleases use
7676
the Debian package on amd64/arm64 or the RPM packages on x86_64/aarch64,
@@ -87,6 +87,11 @@ has_cmd() {
8787
command -v "$1" >/dev/null 2>&1
8888
}
8989

90+
snapd_available() {
91+
has_cmd snap || return 1
92+
snap version 2>/dev/null | grep -Eq '^snapd[[:space:]]+[0-9]'
93+
}
94+
9095
require_cmd() {
9196
if ! has_cmd "$1"; then
9297
error "'$1' is required"
@@ -671,7 +676,7 @@ linux_package_method() {
671676

672677
case "${OPENSHELL_VERSION:-}" in
673678
'' | dev)
674-
if has_cmd snap; then
679+
if snapd_available; then
675680
echo "snap"
676681
return 0
677682
fi
@@ -1450,6 +1455,9 @@ wait_for_user_snap_gateway_listener() {
14501455

14511456
install_linux_snap() {
14521457
require_cmd snap
1458+
snapd_available || error "snapd is not available; ensure snapd is running, then rerun this installer"
1459+
info "waiting for snapd initialization to complete..."
1460+
as_root snap wait system seed.loaded || error "snapd initialization did not complete"
14531461
set_linux_target_runtime_dir
14541462

14551463
if snap list openshell >/dev/null 2>&1; then

‎tasks/scripts/test-install-sh.sh‎

Lines changed: 80 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -100,8 +100,8 @@ assert_glibc_preflight_fails \
100100
"OpenShell Linux packages require glibc >= 2.28; detected musl or unsupported libc." \
101101
setup_ldd_musl
102102

103-
# snap_state: 0 = no snap command, 1 = snap command only,
104-
# installed = the OpenShell snap is already installed.
103+
# snap_state: 0 = no snap command, cli = snap command without a reachable snapd,
104+
# ready = functional snapd, installed = functional snapd with OpenShell installed.
105105
assert_linux_package_method() {
106106
local name=$1
107107
local install_method=$2
@@ -123,7 +123,18 @@ assert_linux_package_method() {
123123
*) return 1 ;;
124124
esac
125125
}
126-
snap() { [ "$*" = "list openshell" ] && [ "$snap_state" = "installed" ]; }
126+
snap() {
127+
case "$1" in
128+
version)
129+
case "$snap_state" in
130+
ready | installed) printf '%s\n' "snap 2.78" "snapd 2.78" ;;
131+
*) return 1 ;;
132+
esac
133+
;;
134+
list) [ "$*" = "list openshell" ] && [ "$snap_state" = "installed" ] ;;
135+
*) return 1 ;;
136+
esac
137+
}
127138
linux_package_method
128139
) >"$out"
129140
actual="$(cat "$out")"
@@ -133,25 +144,59 @@ assert_linux_package_method() {
133144
fi
134145
}
135146

136-
assert_linux_package_method "snap takes precedence over deb and rpm" "" "" 1 1 1 snap
137-
assert_linux_package_method "snap takes precedence over rpm" "" "" 1 0 1 snap
138-
assert_linux_package_method "dev uses snap" "" dev 1 1 1 snap
139-
assert_linux_package_method "explicit snap" snap "" 1 1 1 snap
140-
assert_linux_package_method "explicit snap with dev" snap dev 1 1 1 snap
141-
assert_linux_package_method "explicit snap wins with pinned stable" snap v1.2.3 1 1 1 snap
147+
assert_linux_package_method "snap takes precedence over deb and rpm" "" "" ready 1 1 snap
148+
assert_linux_package_method "snap takes precedence over rpm" "" "" ready 0 1 snap
149+
assert_linux_package_method "dev uses snap" "" dev ready 1 1 snap
150+
assert_linux_package_method "explicit snap" snap "" cli 1 1 snap
151+
assert_linux_package_method "explicit snap with dev" snap dev cli 1 1 snap
152+
assert_linux_package_method "explicit snap wins with pinned stable" snap v1.2.3 cli 1 1 snap
142153
assert_linux_package_method "explicit deb" deb "" installed 0 1 deb
143-
assert_linux_package_method "explicit rpm" rpm "" 1 1 1 rpm
154+
assert_linux_package_method "explicit rpm" rpm "" ready 1 1 rpm
144155
assert_linux_package_method "existing snap install keeps refreshing" "" "" installed 1 1 snap
145156
assert_linux_package_method "existing snap install keeps refreshing dev" "" dev installed 1 1 snap
146157
assert_linux_package_method "pre uses deb despite existing snap" "" pre installed 1 1 deb
147-
assert_linux_package_method "pre uses rpm despite snap" "" pre 1 0 1 rpm
158+
assert_linux_package_method "pre uses rpm despite snap" "" pre ready 0 1 rpm
148159
assert_linux_package_method "numbered prerelease uses deb despite existing snap" "" v0.1.0-pre.3 installed 1 1 deb
149-
assert_linux_package_method "pinned stable uses deb despite snap" "" v1.2.3 1 1 1 deb
160+
assert_linux_package_method "pinned stable uses deb despite snap" "" v1.2.3 ready 1 1 deb
150161
assert_linux_package_method "pinned stable uses rpm despite existing snap" "" v1.2.3 installed 0 1 rpm
151162
assert_linux_package_method "deb is selected without snap" "" "" 0 1 1 deb
152163
assert_linux_package_method "dev uses deb without snap" "" dev 0 1 1 deb
164+
assert_linux_package_method "deb is selected when snapd is unreachable" "" "" cli 1 1 deb
165+
assert_linux_package_method "dev uses rpm when snapd is unreachable" "" dev cli 0 1 rpm
153166
assert_linux_package_method "rpm is selected without snap or deb" "" "" 0 0 1 rpm
154167

168+
if (
169+
has_cmd() { [ "$1" = snap ]; }
170+
snap() { return 1; }
171+
install_linux_snap
172+
) >"$out" 2>"$err"; then
173+
echo "FAIL: explicit snap install should reject unreachable snapd" >&2
174+
exit 1
175+
fi
176+
if ! grep -Fq "snapd is not available" "$err"; then
177+
echo "FAIL: unreachable snapd rejection was not explained" >&2
178+
cat "$err" >&2
179+
exit 1
180+
fi
181+
182+
if (
183+
has_cmd() { [ "$1" = snap ]; }
184+
snap() {
185+
[ "${1:-}" = version ] && printf '%s\n' "snap 2.78" "snapd 2.78"
186+
}
187+
as_root() { return 1; }
188+
info() { :; }
189+
install_linux_snap
190+
) >"$out" 2>"$err"; then
191+
echo "FAIL: explicit snap install should reject failed snapd initialization" >&2
192+
exit 1
193+
fi
194+
if ! grep -Fq "snapd initialization did not complete" "$err"; then
195+
echo "FAIL: failed snapd initialization was not explained" >&2
196+
cat "$err" >&2
197+
exit 1
198+
fi
199+
155200
if (OPENSHELL_INSTALL_METHOD=flatpak linux_package_method) >"$out" 2>"$err"; then
156201
echo "FAIL: unsupported OPENSHELL_INSTALL_METHOD should be rejected" >&2
157202
exit 1
@@ -285,6 +330,7 @@ assert_snap_install_flow() {
285330
}
286331
snap() {
287332
case "${1:-}:${2:-}" in
333+
version:) printf '%s\n' "snap 2.78" "snapd 2.78" ;;
288334
list:docker) return 1 ;;
289335
list:openshell) [ "$openshell_present" = "1" ] ;;
290336
get:openshell) printf '%s\n' system ;;
@@ -342,6 +388,7 @@ assert_snap_user_refresh_flow() {
342388
}
343389
snap() {
344390
case "${1:-}:${2:-}" in
391+
version:) printf '%s\n' "snap 2.78" "snapd 2.78" ;;
345392
list:docker) return 1 ;;
346393
list:openshell) return 0 ;;
347394
get:openshell) printf '%s\n' user ;;
@@ -368,7 +415,8 @@ assert_snap_user_refresh_flow() {
368415
install_linux_snap
369416
) >"$out"
370417
calls="$(cat "$out")"
371-
expected="wait:user-docker
418+
expected="root:snap wait system seed.loaded
419+
wait:user-docker
372420
root:snap refresh openshell --channel=latest/stable
373421
root:snap restart openshell.user-gateway
374422
wait:user-gateway-listener
@@ -384,7 +432,8 @@ wait:gateway-status"
384432
assert_snap_install_flow \
385433
"existing Docker is reused" \
386434
1 0 "" \
387-
"wait:user-docker
435+
"root:snap wait system seed.loaded
436+
wait:user-docker
388437
root:snap install openshell --channel=latest/stable
389438
wait:user-gateway-listener
390439
register:user-gateway
@@ -395,7 +444,8 @@ assert_snap_user_refresh_flow
395444
assert_snap_install_flow \
396445
"existing OpenShell snap is refreshed" \
397446
1 1 "" \
398-
"wait:docker
447+
"root:snap wait system seed.loaded
448+
wait:docker
399449
root:snap refresh openshell --channel=latest/stable
400450
root:snap restart openshell.system-gateway
401451
wait:system-gateway-listener
@@ -412,20 +462,19 @@ if (
412462
}
413463
snap() {
414464
case "${1:-}:${2:-}" in
465+
version:) printf '%s\n' "snap 2.78" "snapd 2.78" ;;
415466
list:docker) return 1 ;;
416467
list:openshell) return 0 ;;
417468
get:openshell) printf '%s\n' disable ;;
418469
*) echo "FAIL: disabled mode reached snap command: $*" >&2; return 99 ;;
419470
esac
420471
}
421472
as_root() {
422-
if [ "${1:-}:${2:-}" = snap:get ]; then
423-
shift
424-
snap "$@"
425-
else
426-
echo "FAIL: disabled mode reached root command: $*" >&2
427-
return 99
428-
fi
473+
case "${1:-}:${2:-}" in
474+
snap:wait) return 0 ;;
475+
snap:get) shift; snap "$@" ;;
476+
*) echo "FAIL: disabled mode reached root command: $*" >&2; return 99 ;;
477+
esac
429478
}
430479
set_linux_target_runtime_dir() { :; }
431480
install_linux_snap
@@ -458,14 +507,17 @@ assert_snap_install_rejected() {
458507
esac
459508
}
460509
snap() {
461-
if [ "${1:-}:${2:-}" = list:docker ]; then
462-
[ "$docker_snap_present" = "1" ]
463-
else
464-
echo "FAIL: ${name}: unexpected snap command: $*" >&2
465-
return 99
466-
fi
510+
case "${1:-}:${2:-}" in
511+
version:) printf '%s\n' "snap 2.78" "snapd 2.78" ;;
512+
list:openshell) return 1 ;;
513+
list:docker) [ "$docker_snap_present" = "1" ] ;;
514+
*) echo "FAIL: ${name}: unexpected snap command: $*" >&2; return 99 ;;
515+
esac
467516
}
468517
as_root() {
518+
if [ "${1:-}:${2:-}" = snap:wait ]; then
519+
return 0
520+
fi
469521
echo "FAIL: ${name}: installation reached root command: $*" >&2
470522
return 99
471523
}

0 commit comments

Comments
 (0)