Skip to content

docs: get started from released packages, not a source build - #667

Merged
bmscomp merged 1 commit into
mainfrom
docs/install-from-packages
Nov 15, 2026
Merged

bmscomp merged 1 commit into
mainfrom
docs/install-from-packages

Conversation

@bmscomp

@bmscomp bmscomp commented Nov 15, 2026

Copy link
Copy Markdown
Owner

Summary

Getting started no longer builds Kates from source. The README, the tutorials, the book and the website now install the released CLI and its prerequisites, then deploy with kates deploy, with no clone of the repository:

brew install kind kubectl helm bmscomp/tap/kates   # with Docker running
kates deploy            # with no cluster reachable, offers to create the 3-zone Kind cluster panda
kates ports
kates test create --type LOAD --records 100000 --wait
kind delete cluster --name panda

On Linux without Homebrew, the docs use scripts/install-kates.sh (checks checksums.txt) or the release tarball, plus cosign. There is no .deb/.rpm; the Homebrew formula already covers Linux.

Building from source (make cli-install, make all, make kates-image-native-local) stays, framed for working on Kates itself: README "Building from source" and a new "Building from Source" subsection in the Deployment Guide.

Pages

  • README: Kind quick start, release notes, teardown
  • website/index.html: "How it works" steps and terminal block
  • Tutorials: 01 steps 1–3 rewritten; prerequisites in README, 07, 14, 15
  • Book: preface "Before You Start", Introduction Quick Start, CLI Reference Installation, Deployment Guide prerequisites / quick deployment / CLI / access points / macOS troubleshooting, Cluster access-points note, Part I page; index regenerated

Corrections found on the way

  • kates deploy on Kind falls back to the published native image when none is local (kindBackendImageArgs); the README said it never pulls one.
  • kates deploy switches kubectl to the cluster it deploys to (useTargetContext); the README said it does not.
  • Tutorial 07 said Kyverno comes with make all; it is opt-in, now --with-kyverno.

Test plan

  • scripts/check-book-style.sh
  • python3 scripts/gen-book-index.py docs/book --check
  • lychee --offline --include-fragments README.md "docs/**/*.md"
  • npx html-validate@9 website/index.html website/work-with-us.html
  • go test ./cmd -run 'TestMCP.*(Doc|Anchor|Ref)'
  • Book render (HTML/PDF) — left to CI
  • Fresh-machine brew install + kates deploy on Kind — not run

The getting-started paths in the README, the tutorials, the book and the
website install Kind, kubectl, Helm and the kates CLI with Homebrew (macOS
or Linux), or on Linux without Homebrew with scripts/install-kates.sh or a
release tarball, then run `kates deploy`, which creates the panda Kind
cluster when none is reachable and pulls the release's published charts
and backend image. No clone of the repository is needed.

Building from source (make cli-install, make all, make
kates-image-native-local) stays, framed for working on Kates itself.

Also corrects two README notes: kates deploy on Kind falls back to the
published native image, and it switches kubectl to the cluster it deploys
to. Tutorial 07 now deploys Kyverno with --with-kyverno, since make all
never installed it.
@bmscomp
bmscomp merged commit 47b4bdb into main Nov 15, 2026
68 checks passed
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.

1 participant