feat(install): install the snap package by default when supported

[olivercalder]

Summary

Make the openshell snap the default installation method again when snapd is installed. It was previously the default in #3656, then made opt-in again in #3726 due to issues with TLS certificates because the gateway was run as a system service instead of a user service. Those issues have since been addressed in #4099, so we can make the snap a default installation target again.

Related Issue

Fixes #4525

Also follows a Slack conversation with @drew about making the snap the default installation method again.

Changes

• 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"

Testing

• Checks appropriate to the affected code and behavior pass
• Unit tests added/updated (if applicable)
• E2E tests added/updated (if applicable)

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• Architecture docs updated (if applicable)

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[krishicks]

I pointed a robot at this and it had feedback which I reviewed, tossed some, and left this. Up to you if you want to make updates.

Low/Medium: has_cmd snap does not show snapd is functional

• The snap binary can be present while snapd is not usable: WSL 2 without systemd (WSL 2 is listed as an experimental platform), containers, or an unseeded snapd.
• Those hosts now select the snap and fail partway through instead of installing the native package.
• Option: also require snap version to report snapd, or require /run/snapd.socket to exist.

Low: crates/openshell-driver-vm/README.md selection description is incomplete or misleading

• The list of conditions that select the Debian package leaves out OPENSHELL_VERSION=pre.
• The RPM paragraph says "Select it explicitly with OPENSHELL_INSTALL_METHOD=rpm", which suggests RPM always needs the override. RPM is still selected automatically on hosts without snap, and for pinned or prerelease versions.

Nit: Migration instructions in docs/about/installation.mdx overstate the need for the ack flag

• "remove the existing installation … then rerun the script with OPENSHELL_ACK_BREAKING_UPGRADE=1": once the native installation is removed, guard_native_to_snap_transition does not trigger, so the flag only matters if an openshell binary is left in ~/.local/bin, /usr/local/bin, or /usr/bin. This wording predates the PR.

Low: README quickstart prerequisites not updated

• README.md doesn't mention that on hosts with snap, the default install now requires Docker Engine from a system package or Docker's repository, and that the Docker snap is not supported. It also doesn't mention the OPENSHELL_INSTALL_METHOD=deb|rpm override for Podman or VM-driver users.

[krishicks]

/ok to test 239405c

[olivercalder]

Thanks for the review @krishicks ! I've pushed a commit to improve the things you pointed out.

[TaylorMutch]

/ok to test e15b8bf

[github-actions]

Compatibility review (advisory)

Unaddressed breaking changes

The default Linux installer now selects snap on snapd hosts instead of the documented native package. This breaks native upgrades and Docker-free Podman or VM installations despite documented overrides.

1. cli — ACKED

install.sh with unset OPENSHELL_INSTALL_METHOD changed from selecting deb/rpm to selecting snap whenever snapd is available.

• Impact: Existing native installations now stop for manual migration, while fresh Podman or VM users on snapd hosts fail unless Docker is installed or a native method is explicitly selected.
• Action: Keep deb/rpm as the unset default for this non-breaking train and require OPENSHELL_INSTALL_METHOD=snap to opt in; the documented deb/rpm override does not make the default change compatible.
• PR: feat(install): install the snap package by default when supported #4380

Review details

• Execution: complete
• Candidate: PR #4380 (309f9092a4a5849802febeaa32893910c474e69b)
• Baseline: 82977e27a438c8a6a1072498432f9f7c75a33a85 (82977e27a438c8a6a1072498432f9f7c75a33a85)
• Reviewed: rust-sdk, python-sdk, go-sdk, typescript-sdk, api-behavior, cli, configuration, policy, helm, state

Advisory review; publication gates are unchanged.

Branch check run

[olivercalder]

Unaddressed breaking changes

The default Linux installer now selects snap on snapd hosts instead of the documented native package. This breaks native upgrades and Docker-free Podman or VM installations despite documented overrides.

Yes, this is the intention of the PR. The OPENSHELL_INSTALL_METHOD=deb|rpm override is there to allow backwards compatibility, but the intention is for users to use the openshell snap where available, as this provides automatic updates in the future, along with rollback capabilities, a self-contained install, and extra sandboxing.

[krishicks]

Due to a new rule you need to create an issue for this (see failed CI checks). I think this PR predates that change, which is unfortunate.

[elezar]

Could we include Docker compatibility in the automatic Snap-selection check?

Currently, linux_package_method() selects Snap whenever snapd is available and the version is unset or dev, but install_linux_snap() subsequently rejects hosts with the Docker snap or without Docker. This makes the default installer fail on hosts where it previously selected a native package, including Podman or VM setups.

For fresh installations, I suggest selecting Snap automatically only when Docker is present and the Docker snap is absent, otherwise falling back to DEB/RPM. Explicit OPENSHELL_INSTALL_METHOD=snap should retain the current preflight errors, and existing OpenShell Snap installations should remain on the Snap path.

Could we add selection tests for these cases? The canary’s automatic-selection rejection cases would also need updating, while retaining rejection coverage for explicit Snap requests.

This fallback would preserve native installation options; it would not establish compatibility between native OpenShell and the Docker snap, given the AppArmor limitation documented in #3666.

[olivercalder]

For fresh installations, I suggest selecting Snap automatically only when Docker is present and the Docker snap is absent, otherwise falling back to DEB/RPM. Explicit OPENSHELL_INSTALL_METHOD=snap should retain the current preflight errors, and existing OpenShell Snap installations should remain on the Snap path.

I tinkered with implementing this but was left unsatisfied with the result...

I don't think it's correct to fall back to native package installations for the deb (not the rpm) if there's not a non-snap Docker daemon installed: if the user doesn't have docker/podman/vm backends installed, then that just leaves them with a non-functional non-distro .deb package, instead of a non-functional snap. If I'm a new user who hears about OpenShell in the news and wants to give it a try, I probably don't have any backend already installed, and I expect to just run install.sh and get a working setup. Unfortunately, for the deb and the snap, we do require prerequisite setup from the user, it's just implicit for the deb and explicit for the snap.

The short-mid goal IMO, once the docker snap is compatible with OpenShell (which is in progress: canonical/snapd#17730 and canonical/docker-snap#405), then we can have install.sh automatically install the docker snap if docker is not already installed, and then install the openshell snap and configure the gateway nicely. I think the raw .deb package is almost always the wrong option, unless a user explicitly wants to use a non-docker driver and already has their machine pre-setup to do so. At the very least, the user would need to change the configuration to use the VM driver for the .deb if they don't already have/want to install docker or podman. Slightly more medium-term, I think it should be possible to add support for podman and the VM driver to the snap, in which case there would be little if any reason to choose the .deb over the snap.

The .rpm package is different though. The .deb doesn't pull in any compute backend as a dependency (though it ships the VM driver, while the .rpm does pull in podman as a dependency. So rpm users will get a functional system, while deb users will not at the moment without manual configuration to use the VM driver, which install.sh does not currently do.

So where does that leave us? Here's the decision flow I would propose:

1. If openshell is already installed via some method, it's probably best to continue to update via that same method, so if .deb is already installed, update to the newer .deb rather than install the snap
2. If a non-snap Docker daemon is installed along with snapd, then we should install the OpenShell snap as proposed in the existing PR
3. If the system package manager uses .rpms, then install the standalone .rpm file, which pulls in Podman and Just Works™
4. If the system package manager uses .debs, by this time we know the user doesn't have Docker installed else we would have chosen the snap, so it's likely they wouldn't end up with a functional OpenShell install regardless of whether they installed the .deb or the snap. So I would propose the following for the time being:
   1. Do the checks for docker presence during package method selection instead of only during the snap install function, and extend the checks to include podman so we know whether it's safe to fall back to the .deb package and use podman
   2. If it's not clear that there is Docker or Podman currently installed, abort install.sh with an error message so that they don't end up with a non-functional install, and instead tell them what they need to do:
   3. Say that the user must either install the Docker daemon and re-run install.sh, or use a OPENSHELL_INSTALL_METHOD override to manually select a package method, either deb if they want to use Podman (which they should install/set up first) or the VM driver (which they will need to configure manually after install), otherwise snap if they just want to just talk to a remote install and don't need a local gateway driver
   4. We'd need to remove/ignore the strict requirements for docker presence from the install_linux_snap() if the user manually sets OPENSHELL_INSTALL_METHOD=snap in the latter case

These are my initial thoughts on the topic, happy to discuss more or be overridden. I'll talk about this issue with others on my team to to get their advice.

[olivercalder]

I've opened #4627 which should hopefully address much of the complexity in question by removing all the special caveats and docker checks required for the snap, since it should just work on its own using the VM driver. So I'll revisit this PR after that new PR (hopefully) lands.