fix(install): preflight zstd before Ollama Linux installer and explain sudo prompts

[zyang-dev]

Summary

On Debian/Ubuntu hosts without zstd, the Ollama Linux installer aborts during archive extraction. Onboard's install-ollama path now preflights zstd via apt-get before piping the installer, and the install-ollama sudo steps print info lines up front explaining what sudo is for.

Changes

• src/lib/onboard.ts:
  • New ensureOllamaLinuxExtractionDependencies() short-circuits if zstd is already present (via hostCommandExists); otherwise runs sudo apt-get update -qq && sudo apt-get install -y -qq --no-install-recommends zstd. Non-apt distros get a clear error pointing at the equivalent dnf / pacman commands.
  • Added info lines before the zstd install, before curl -fsSL https://ollama.com/install.sh | sh (since the installer itself uses sudo to create the ollama user and install the systemd unit), and before the systemd loopback override.
  • Removed the now-redundant "Installing Ollama via official installer..." log; the new sudo-context line replaces it.
• test/onboard-selection.test.ts:
  • Tests assert the zstd preflight command runs before ollama.com/install.sh, in both the interactive and non-interactive install-ollama paths.
  • New events array captures both run-commands and log lines with order preserved; assertions verify each sudo info line is emitted before its corresponding command.
  • Added stdout-content assertions for the systemd-override info line in the systemd-failure test.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Verification

• npx prek run --all-files passes
• npm test passes
• Tests added or updated for new or changed behavior
• No secrets, API keys, or credentials committed
• Docs updated for user-facing behavior changes
• make docs builds without warnings (doc changes only)
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: zyang-dev 267119621+zyang-dev@users.noreply.github.com

Summary by CodeRabbit

• New Features

  • Added automatic prerequisite detection to Linux Ollama installation flow

• UX Improvements

  • Refined installation instructions with clearer messaging for system configuration steps

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 88414ac8-a11e-447c-80f2-9f0199aaffb2

📥 Commits

Reviewing files that changed from the base of the PR and between edbcd78 and 01fd0ca.

📒 Files selected for processing (2)

• src/lib/onboard.ts
• test/onboard-selection.test.ts

---

📝 Walkthrough

Walkthrough

This PR adds zstd prerequisite validation to the Linux Ollama onboarding flow, ensuring the dependency is installed before running the official installer. It also refines user-facing messaging around sudo/systemd behavior and extends test coverage to verify preflight command ordering and messaging sequences.

Changes

Ollama Linux zstd prerequisites and installer flow

Layer / File(s)	Summary
zstd prerequisite dependency helper src/lib/onboard.ts	New ensureOllamaLinuxExtractionDependencies() helper verifies zstd availability and installs it via sudo apt-get when missing, with apt-get availability guard.
Ollama installer flow and systemd override messaging src/lib/onboard.ts	Linux installer flow now calls the zstd helper before proceeding, expanded instructions document sudo/systemd/service behavior, and systemd override messaging details drop-in/daemon-reload/restart steps.
Test event capture and mock instrumentation test/onboard-selection.test.ts	Structured events array captures command invocations and log output; runner and console mocks are instrumented to push normalized events for ordering assertions.
Test assertions for install ordering and messaging test/onboard-selection.test.ts	Validates zstd preflight apt-get runs before Ollama installer script, verifies systemd override messaging appears in expected sequence, and confirms preflight ordering in interactive and non-interactive install flows.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

🐰 A fluffy fix for a zstd prerequisite,
Before the Ollama quest can submit!
With systemd notes and messaging bright,
The tests now verify the flow is right.
Prerequisites checked with ordered delight! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly and specifically describes the main change: adding a preflight zstd check before the Ollama Linux installer and improving user-facing messaging about sudo prompts.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/ollama-zstd-preflight

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

E2E Advisor Recommendation

Required E2E: gpu-e2e, gpu-double-onboard-e2e
Optional E2E: ollama-proxy-e2e, onboard-resume-e2e, onboard-repair-e2e, cloud-onboard-e2e

Dispatch hint: gpu-e2e,gpu-double-onboard-e2e

Workflow run

Full advisor summary

Pi Semantic E2E Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

• gpu-e2e: Only E2E that exercises the real Linux install-ollama branch end-to-end (NEMOCLAW_PROVIDER=ollama on a fresh GPU runner): curl|sh installer, systemd loopback override, auth proxy start, live Ollama inference. The added zstd preflight and new sudo warnings run here, so any regression in ordering, fail-closed behavior, or binding must be caught.
• gpu-double-onboard-e2e: Re-onboard with Ollama on a Linux host hits the same install-ollama / systemd loopback override path a second time. Validates idempotency of the new zstd preflight + sudo prompts and guards against proxy-token drift (ollama proxy token diverges from stored token after re-onboard, causing persistent HTTP 401 on inference #2553) regressions intersecting with the install path.

Optional E2E

• ollama-proxy-e2e: Installs real Ollama on ubuntu-latest and validates the auth proxy end-to-end. Good confidence check that the zstd preflight does not break Ollama extraction on stock GitHub-hosted Ubuntu, even though this script does not route through nemoclaw onboard itself.
• onboard-resume-e2e: onboard.ts is a large file; the install-ollama branch sits inside setupNim selectionLoop. Running the generic onboard resume path gives a cheap regression net for control-flow edits near the changed code.
• onboard-repair-e2e: Covers onboard state-repair paths that share helpers with the modified Linux Ollama install branch (secureTempFile, runShell sudo usage, host command detection).
• cloud-onboard-e2e: General non-interactive onboard smoke on fresh ubuntu-latest. Confirms the new warnings/exit paths do not leak into non-Ollama selections and that setupNim() branching still reaches the cloud provider.

New E2E recommendations

• onboard-installer (medium): No existing E2E exercises a Linux host that is missing zstd. GPU runners and ubuntu-latest typically ship with zstd preinstalled, so the new sudo apt-get preflight branch (the riskiest code in this PR — it runs privileged commands and fails closed on non-apt systems) is not actually hit by any current workflow. Regressions here would only be caught on real user machines.
  • Suggested test: Add a host-level E2E job (e.g., test/e2e/test-onboard-ollama-linux-fresh.sh) that runs in a container or VM where zstd is removed (apt-get purge zstd) and ollama is not installed, then asserts: (1) onboard logs the zstd warning before invoking apt-get, (2) sudo apt-get install zstd runs and succeeds, (3) the ollama.com installer then runs and extracts successfully, (4) OLLAMA_HOST is bound only to 127.0.0.1. Also add a negative variant on a non-apt container (e.g., fedora/alpine with zstd missing) asserting onboard exits 1 with the 'only apt-based Linux is supported here' message and does NOT attempt the curl|sh installer.

Dispatch hint

• Workflow: nightly-e2e.yaml
• jobs input: gpu-e2e,gpu-double-onboard-e2e

[ericksoa]

Reviewed current head 01fd0ca, including an adversarial pass over the Linux Ollama install path. The change is scoped to zstd preflight and sudo-context messaging for install-ollama, keeps loopback safety intact, and has relevant targeted coverage. All visible checks and CodeRabbit are green.