Skip to content

docs: restructure install paths around user intent - #599

Open
viniciusdc wants to merge 3 commits into
mainfrom
docs/pixi-install-paths-563
Open

docs: restructure install paths around user intent#599
viniciusdc wants to merge 3 commits into
mainfrom
docs/pixi-install-paths-563

Conversation

@viniciusdc

@viniciusdc viniciusdc commented Aug 15, 2026

Copy link
Copy Markdown
Collaborator

Part of #563.

What

Restructures the README install section around user intent instead of leading with "build from source":

  • A Nebi starter workspace (recommended) - the path this epic built, where the toolchain and the config pin together.
  • pixi, either into an existing project (pins in pixi.lock) or as a machine-wide CLI.
  • Homebrew cask for macOS.
  • Release archives, with the naming scheme spelled out and a pointer to the verification steps.
  • From source, moved to a contributor-facing subsection.

### Deploy now says which invocation belongs to which install. It described a source checkout, which was correct while make build was the only documented path and wrong for five of the six paths this PR adds.

Why the commands changed since the draft

The draft documented intent. With the channel and the starters published, every command was run, and several were wrong:

  • nebi import extracts into the current directory (-o defaults to "."), so the draft's cd local failed for every reader. Now passes -o local.
  • pixi add has no --channel flag - the draft's form fails with unexpected argument '--channel' found. The channel goes into the manifest first, via pixi workspace channel add.
  • The channel URL was the shared github-releases one. nic is on https://prefix.dev/nebari-dev/nebari. Moving to the shared channel is Move nic to the shared prefix.dev github-releases channel and delete the bridge #620.
  • Homebrew ships a cask, not a formula, so brew install --cask.
  • Archives are not all .tar.gz - Windows ships .zip, <os> renders darwin rather than macos, and <version> carries no leading v.
  • nebi needed a floor. Below 0.10.5 the import silently produces only pixi.toml and pixi.lock - no config.yaml - so the promise next to it was false with no error. CI pins >=0.13; that is what the README now installs. (release.yml's adjacent comment claims a 0.10 floor and is itself inaccurate.)
  • -c conda-forge was unnecessary. The package has no dependencies (depends: [] on every platform), and both pixi lock and pixi global install resolve against our channel alone.

Two docs corrected alongside

docs/operations/packaging.md and starters/templates/pixi.toml.tmpl both stated that the channel was empty and that the nic dependency would not resolve until the first pipeline-driven release. v0.14.0 was seeded by hand and resolves today, so with this PR telling readers to install from that channel the repo asserted both things at once. The template ships inside every generated starter, so it is the one that mattered.

How to test

pixi global install -c conda-forge "nebi-cli>=0.13"
nebi import quay.io/nebari/starters/local:v0.14.0 -o local
cd local && pixi install && pixi run nic version

And the project-scoped path:

pixi workspace channel add https://prefix.dev/nebari-dev/nebari
pixi add nebari-infrastructure-core

Both verified on linux-64 against the published v0.14.0. pixi global install was verified without -c conda-forge. The Homebrew cask was checked against .goreleaser.yml and the Casks/nic.rb in nebari-dev/homebrew-tap rather than run, since it is macOS-only.

Scope

Two items on #563 are deliberately not here, which is why this is Part of rather than Closes:

  • The docs-site mirror. Two docs still say nic is distributed via the shared github-releases channel #622 tracks three remaining stale claims across two files, and the mirror makes sense alongside those rather than piecemeal.
  • Links from the starter workspace READMEs to the install docs. starters/templates/README.local.md and README.aws.md still only say "Install the pinned toolchain: pixi install". Small, but it belongs with whatever next touches those templates.

Two follow-ups this PR deliberately leaves to #539, which is already editing both files and would conflict:

Reorganize the README install section by how people actually install nic:
pixi (recommended, pending the prefix.dev channel), Homebrew, release
archives with signature verification, and from-source for contributors.
Scope the Go 1.26+ prerequisite to source builds only.

Draft: the pixi path depends on #579, the install-script and Homebrew
sections overlap #539, and the docs-site mirror is still pending.

Part of #563.
The pixi commands were written against intent rather than a working
channel, and two of the three were wrong: pixi add takes no --channel
flag, and the channel is our own rather than the shared github-releases
one. Both forms are now the ones verified against the published package.

Leads on the Nebi starter workspace, since that is the path where the
toolchain and the config pin together, and names the Homebrew cask with
--cask so it resolves.
@viniciusdc
viniciusdc marked this pull request as ready for review September 1, 2026 15:46
@viniciusdc
viniciusdc force-pushed the docs/pixi-install-paths-563 branch from 232b1c9 to e702f67 Compare September 1, 2026 15:47
@viniciusdc viniciusdc changed the title docs: restructure install paths around user intent (WIP) docs: restructure install paths around user intent Sep 1, 2026
The recommended path's second command could not work: nebi import
extracts into the current directory, so `cd local` failed for every
reader. It now passes -o explicitly.

Deploy was left describing a source checkout while the section above it
had just added five other ways to install, so `./nic` and the
`cp examples/...` block were wrong for most readers - and the copy would
have clobbered the config.yaml the starter ships. Deploy now says which
invocation belongs to which install.

Also: name the nebi floor, since older versions ship a partial workspace
with no error; correct the archive naming, which claimed .tar.gz for
Windows and hid that the version carries no leading v; and drop
-c conda-forge, which nothing needs - the package has no dependencies.

packaging.md and the starter template both still said the channel was
empty and the dependency would not resolve. It does.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants