Skip to content

Commit d69af11

Browse files
committed
feat(install): install the snap package by default when supported
- `install.sh` now selects snap when the `snap` command exists and `OPENSHELL_VERSION` is unset or `dev`. - Explicit `OPENSHELL_INSTALL_METHOD=snap|deb|rpm` still takes precedence. - Exact releases and prereleases continue to use native packages during automatic selection. - Docker-related snap errors now mention DEB/RPM overrides. - Installer selection tests cover default snap selection, native fallbacks, overrides, pinned releases, and prereleases. - Snap canary jobs no longer force `OPENSHELL_INSTALL_METHOD=snap`, so they test automatic selection. - Updated installation, VM driver, release canary, CI, and test guest documentation. - Fixed some leftover "Snap" language which should be "snap" Signed-off-by: Oliver Calder <oliver.calder@canonical.com>
1 parent 82977e2 commit d69af11

9 files changed

Lines changed: 51 additions & 44 deletions

File tree

‎.agents/skills/test-release-canary/SKILL.md‎

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,8 @@ The Release Canary (`.github/workflows/release-canary.yml`) smoke-tests the arti
1616
| `macos` | `macos-latest-xlarge` | Installs the dev Homebrew artifacts, reaches the VM gateway, and creates, executes in, and deletes a sandbox. |
1717
| `ubuntu-deb` | `ubuntu-latest` | Installs the dev Debian package, reaches the Docker gateway, and creates, executes in, and deletes a sandbox. |
1818
| `fedora` | `fedora:latest` container | Installs the dev RPM packages, reaches the Podman gateway, and creates, executes in, and deletes a sandbox. |
19-
| `ubuntu-snap-system-docker` | `ubuntu-latest` | Uses `install.sh` to install the snap from `latest/edge`, reuses system Docker, verifies the packaged prover version and a local policy boundary check, reaches the Docker gateway, creates, executes in, and deletes a sandbox, and verifies that the Docker snap is not installed. |
20-
| `ubuntu-snap-docker-preflight` | `ubuntu-latest` | Verifies that `install.sh` rejects the OpenShell snap path when Docker is absent or supplied by the Docker snap, without installing OpenShell. |
19+
| `ubuntu-snap-system-docker` | `ubuntu-latest` | Verifies that `install.sh` selects the snap automatically when the `snap` command is available, installs it from `latest/edge`, reuses system Docker, verifies the packaged prover version and a local policy boundary check, reaches the Docker gateway, creates, executes in, and deletes a sandbox, and verifies that the Docker snap is not installed. |
20+
| `ubuntu-snap-docker-preflight` | `ubuntu-latest` | Verifies that automatic snap selection rejects installation when Docker is absent or supplied by the Docker snap, without installing OpenShell. |
2121
| `kubernetes` | `ubuntu-latest` + kind | Installs the dev Helm chart, reaches the in-cluster gateway, and creates, executes in, and deletes a sandbox using the published runtime images. |
2222

2323
All canary jobs disable anonymous OpenShell telemetry. Host package jobs inject
@@ -26,11 +26,13 @@ Kubernetes job installs with `server.telemetryEnabled=false`, so smoke traffic
2626
does not contribute to product usage metrics.
2727

2828
The workflow sets `OPENSHELL_VERSION=dev` for every `install.sh` job. Positive
29-
jobs consume the rolling dev release produced by the triggering workflow. The
30-
system-Docker snap lane tracks `latest/edge`; the missing-Docker lane exits
31-
before installing a snap. The Debian and Kubernetes CLI lanes remove snapd so
32-
they continue to exercise the dev Debian package. Kubernetes pins the matching
33-
`0.0.0-dev` chart and `:dev` images.
29+
jobs consume the rolling dev release produced by the triggering workflow. Both
30+
snap lanes rely on the installed `snap` command to exercise automatic snap
31+
selection without setting `OPENSHELL_INSTALL_METHOD`. The system-Docker lane
32+
tracks `latest/edge`; the missing-Docker lane exits before installing a snap.
33+
The Debian and Kubernetes CLI lanes remove snapd so they continue to exercise
34+
the dev Debian package. Kubernetes pins the matching `0.0.0-dev` chart and
35+
`:dev` images.
3436

3537
RPM package installation also has tmachine conformance coverage in
3638
`Branch E2E Checks` (with `test:e2e`), `Release Dev`, and `Release Tag`. Those

‎.github/workflows/release-canary.yml‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -195,8 +195,6 @@ jobs:
195195
name: Ubuntu snap with system Docker
196196
if: ${{ github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success' }}
197197
runs-on: ubuntu-latest
198-
env:
199-
OPENSHELL_INSTALL_METHOD: snap
200198
timeout-minutes: 20
201199
steps:
202200
- name: Install snapd
@@ -297,8 +295,6 @@ jobs:
297295
name: Ubuntu snap Docker preflight
298296
if: ${{ github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success' }}
299297
runs-on: ubuntu-latest
300-
env:
301-
OPENSHELL_INSTALL_METHOD: snap
302298
timeout-minutes: 20
303299
steps:
304300
- name: Install snapd

‎CI.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -571,7 +571,7 @@ These workflows run after merge to publish dev/tagged artifacts and verify them.
571571
| `.github/workflows/release-tag.yml` | Publishes stable releases and pre-releases on tag pushes or manual dispatch. Release Auto-Tag dispatches it explicitly because its `GITHUB_TOKEN` pushes do not trigger workflows. Both require the currently implemented qualification profile to pass before publication; the summary identifies the remaining RFC 0014 coverage. Failed candidates retain build artifacts and evidence in Actions storage. Source-SHA OCI images remain available as qualification inputs. |
572572
| `.github/workflows/snap-package.yml` | Builds snap and component artifacts for Release Dev and Release Tag without Store credentials or publication. |
573573
| `.github/workflows/snap-publish.yml` | Uploads existing snap and component artifacts to the Store without rebuilding. Release Dev calls it directly for `latest/edge` after snap builds and requires it to succeed before creating the dev release. Release Tag calls it for `latest/stable` only for stable releases, after qualification and release assembly succeed. |
574-
| `.github/workflows/release-canary.yml` | Smoke-tests published dev artifacts in the `macos`, `ubuntu-deb`, `ubuntu-snap-system-docker`, `fedora`, and `kubernetes` (kind + Helm) jobs. Each job reaches its gateway and creates, exercises, and deletes a sandbox. The `ubuntu-snap-system-docker` job verifies a compatible system Docker lifecycle, while `ubuntu-snap-docker-preflight` tests fail-fast behavior when Docker is absent or supplied by the Docker snap. The positive snap lane also runs a local policy containment check with the packaged prover. It runs automatically after `Release Dev` succeeds and supports manual dispatch (`gh workflow run release-canary.yml --ref <branch>`). See the `test-release-canary` skill for the playbook and local kind reproduction. |
574+
| `.github/workflows/release-canary.yml` | Smoke-tests published dev artifacts in the `macos`, `ubuntu-deb`, `ubuntu-snap-system-docker`, `fedora`, and `kubernetes` (kind + Helm) jobs. Each job reaches its gateway and creates, exercises, and deletes a sandbox. The snap jobs verify that `install.sh` selects the snap automatically when the `snap` command is available. The `ubuntu-snap-system-docker` job verifies a compatible system Docker lifecycle, while `ubuntu-snap-docker-preflight` tests fail-fast behavior when Docker is absent or supplied by the Docker snap. The positive snap lane also runs a local policy containment check with the packaged prover. It runs automatically after `Release Dev` succeeds and supports manual dispatch (`gh workflow run release-canary.yml --ref <branch>`). See the `test-release-canary` skill for the playbook and local kind reproduction. |
575575

576576
## Required status contexts
577577

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

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -311,14 +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 from the selected `OPENSHELL_VERSION` release tag. That package
315-
includes `openshell-gateway` and `openshell-driver-vm`, but leaves
314+
Debian package when the `snap` command is unavailable, automatic selection
315+
receives an exact `OPENSHELL_VERSION` release tag, or
316+
`OPENSHELL_INSTALL_METHOD=deb` is set. That package includes
317+
`openshell-gateway` and `openshell-driver-vm`, but leaves
316318
`OPENSHELL_COMPUTE_DRIVER` unset so the gateway uses its normal runtime
317319
auto-detection. Set `OPENSHELL_COMPUTE_DRIVER=vm` to force the VM driver.
318320
319-
On RPM-family Linux x86_64 and aarch64 systems, `install.sh` installs the
320-
`openshell` and `openshell-gateway` RPM packages from the selected release tag.
321-
The RPM gateway package is configured for the Podman driver.
321+
On RPM-family Linux x86_64 and aarch64 systems, the equivalent native path
322+
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.
322325
323326
On Apple Silicon macOS, `install.sh` stages the generated `openshell.rb`
324327
formula from the selected release in the `nvidia/openshell` Homebrew tap.

‎docs/about/installation.mdx‎

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

8787
## Linux
8888

89-
The script installs a Debian package on Debian and Ubuntu or an RPM package on Fedora and RHEL. Set `OPENSHELL_INSTALL_METHOD=snap` to install the [snap](#snap) package instead; hosts that already have the OpenShell snap keep refreshing it. Linux packages require glibc 2.28 or newer.
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`.
9090

91-
The gateway runs as a systemd user service at `https://127.0.0.1:17670` and reads `~/.config/openshell/gateway.toml`.
91+
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.
92+
93+
For Debian and RPM installations, the gateway runs as a systemd user service at `https://127.0.0.1:17670` and reads `~/.config/openshell/gateway.toml`.
9294

9395
Both Debian and RPM load `~/.config/openshell/gateway.env` for configuration
9496
preflight and gateway startup. Use it to select exact trusted runtime artifacts
@@ -119,9 +121,9 @@ sudo loginctl enable-linger $USER
119121

120122
## Snap
121123

122-
The snap requires Docker Engine installed from your distribution or Docker's package repository. The Docker snap is not compatible.
124+
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`.
123125

124-
The snap does not migrate existing Debian, RPM, or Homebrew installs. Remove any existing installation first, then either rerun the `install.sh` script with `OPENSHELL_INSTALL_METHOD=snap 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 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:
125127

126128
```shell
127129
sudo snap install openshell

‎install.sh‎

Lines changed: 13 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,8 @@
44
#
55
# Install OpenShell from a GitHub release.
66
#
7-
# Linux installs either the Debian or RPM packages from the selected release.
7+
# Linux automatically installs the snap when the snap command is available and
8+
# the version is unset or dev; exact releases and prereleases use native packages.
89
# Apple Silicon macOS installs the generated Homebrew formula, so Homebrew owns
910
# the binary layout and launchd service lifecycle.
1011
#
@@ -63,19 +64,19 @@ ENVIRONMENT VARIABLES:
6364
pre-v0.0.37 or non-snap installation.
6465
OPENSHELL_INSTALL_METHOD
6566
Linux package to install: snap, deb, or rpm. Unset
66-
selects deb or rpm from the host package manager.
67+
selects snap when available, otherwise deb or rpm.
6768
6869
NOTES:
6970
When OPENSHELL_VERSION is unset, this resolves the latest tagged release
7071
from ${GITHUB_URL}/releases/latest.
7172
72-
Linux installs the Debian package on amd64/arm64 or the RPM packages on
73-
x86_64/aarch64, depending on the host package manager. Set
74-
OPENSHELL_INSTALL_METHOD=snap to install the OpenShell snap instead; hosts
75-
that already have the OpenShell snap keep refreshing it. snap installs use
76-
latest/stable by default and latest/edge for dev, and do not support
77-
explicit release tags or prereleases. The OpenShell snap requires a running
78-
Docker Engine installed from a system package or Docker's package
73+
Linux installs the OpenShell snap when the snap command is available and
74+
OPENSHELL_VERSION is unset or dev. Snap installs use latest/stable by
75+
default and latest/edge for dev. Explicit release tags and prereleases use
76+
the Debian package on amd64/arm64 or the RPM packages on x86_64/aarch64,
77+
depending on the host package manager. Set OPENSHELL_INSTALL_METHOD=deb or
78+
rpm to select a native package explicitly. The OpenShell snap requires a
79+
running Docker Engine installed from a system package or Docker's package
7980
repository. The Docker snap is not currently compatible with OpenShell.
8081
macOS installs the release Homebrew formula on Apple Silicon and starts a
8182
brew services-backed local gateway.
@@ -668,11 +669,9 @@ linux_package_method() {
668669
*) error "unsupported OPENSHELL_INSTALL_METHOD=${OPENSHELL_INSTALL_METHOD}; use snap, deb, or rpm" ;;
669670
esac
670671

671-
# Keep refreshing an existing snap install instead of adding a second
672-
# gateway on the same port.
673672
case "${OPENSHELL_VERSION:-}" in
674673
'' | dev)
675-
if has_cmd snap && snap list openshell >/dev/null 2>&1; then
674+
if has_cmd snap; then
676675
echo "snap"
677676
return 0
678677
fi
@@ -1467,11 +1466,11 @@ install_linux_snap() {
14671466

14681467
if snap list docker >/dev/null 2>&1; then
14691468
error "the Docker snap is not currently compatible with OpenShell because its AppArmor confinement prevents OpenShell's hardened containers from starting.
1470-
Remove the Docker snap and install Docker Engine from a system package or Docker's package repository, then rerun this installer."
1469+
Remove the Docker snap and install Docker Engine from a system package or Docker's package repository, then rerun this installer. To use a native OpenShell package instead, set OPENSHELL_INSTALL_METHOD=deb or OPENSHELL_INSTALL_METHOD=rpm."
14711470
fi
14721471
if ! has_cmd docker; then
14731472
error "Docker is required before installing the OpenShell snap.
1474-
Install Docker Engine from a system package or Docker's package repository, then rerun this installer. The Docker snap is not currently compatible with OpenShell."
1473+
Install Docker Engine from a system package or Docker's package repository, then rerun this installer. The Docker snap is not currently compatible with OpenShell. To use a native OpenShell package instead, set OPENSHELL_INSTALL_METHOD=deb or OPENSHELL_INSTALL_METHOD=rpm."
14751474
fi
14761475
info "using existing Docker installation"
14771476
if [ "$_existing_mode" = user ]; then

‎nix/test-guest/README.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -78,10 +78,10 @@ The root [`flake.nix`](../../flake.nix) exposes this directory as the `test-gues
7878
| Fedora 44 | No | Yes | Yes | Yes | `.rpm` |
7979
| Rocky Linux 9 | Yes | Yes | No | Yes | `.rpm` |
8080

81-
The `snapd` configuration is available for Ubuntu and prepares snapd for snap
82-
Store installation experiments. Combine it with `docker` to reproduce the
83-
system-Docker canary, or use it alone to verify that `install.sh` fails safely
84-
when Docker is absent.
81+
The `snapd` configuration is available for Ubuntu and prepares snapd to
82+
reproduce `install.sh` automatic snap selection. Combine it with `docker` to
83+
reproduce the system-Docker canary, or use it alone to verify that `install.sh`
84+
fails safely when Docker is absent.
8585

8686
`podman-rootless` configures the explicit rootless Podman guest setup used by
8787
OpenShell tests. It supports Fedora and Ubuntu 26.04 or later. Ubuntu adds the

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

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -133,19 +133,23 @@ assert_linux_package_method() {
133133
fi
134134
}
135135

136-
assert_linux_package_method "deb is the default despite snap" "" "" 1 1 1 deb
137-
assert_linux_package_method "rpm is the default despite snap" "" "" 1 0 1 rpm
138-
assert_linux_package_method "dev uses deb despite snap" "" dev 1 1 1 deb
139-
assert_linux_package_method "snap is opt-in" snap "" 1 1 1 snap
140-
assert_linux_package_method "snap opt-in with dev" snap dev 1 1 1 snap
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
141142
assert_linux_package_method "explicit deb" deb "" installed 0 1 deb
142143
assert_linux_package_method "explicit rpm" rpm "" 1 1 1 rpm
143144
assert_linux_package_method "existing snap install keeps refreshing" "" "" installed 1 1 snap
144145
assert_linux_package_method "existing snap install keeps refreshing dev" "" dev installed 1 1 snap
145146
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
146148
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
147150
assert_linux_package_method "pinned stable uses rpm despite existing snap" "" v1.2.3 installed 0 1 rpm
148151
assert_linux_package_method "deb is selected without snap" "" "" 0 1 1 deb
152+
assert_linux_package_method "dev uses deb without snap" "" dev 0 1 1 deb
149153
assert_linux_package_method "rpm is selected without snap or deb" "" "" 0 0 1 rpm
150154

151155
if (OPENSHELL_INSTALL_METHOD=flatpak linux_package_method) >"$out" 2>"$err"; then

‎tasks/scripts/test-packaging-assets.sh‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -239,6 +239,7 @@ assert_contains "$snap_canary" "install.sh | sh"
239239
assert_contains "$snap_canary" "ubuntu-snap-system-docker:"
240240
assert_contains "$snap_canary" "ubuntu-snap-docker-preflight:"
241241
assert_contains "$snap_canary" "openshell.prover check"
242+
assert_not_contains "$snap_canary" "OPENSHELL_INSTALL_METHOD"
242243
assert_not_contains "$snap_canary" "--dangerous"
243244
assert_not_contains "$snap_canary" "snap connect openshell:docker"
244245
if ! awk '/config preflight/ { seen = 1 } /generate-certs/ { exit !seen }' "$service"; then

0 commit comments

Comments
 (0)