docs: split local-dev quickstart from cluster deployment guide; add auth demo video - #97
Conversation
… demo video The Quick Start conflated two audiences: its prerequisites (Docker, k3d) were local-dev tooling, yet it led with a production 'helm install oci://...'. Split them: - 'Quick Start (local development)' is now explicitly the make-dev/k3d path for evaluating and developing SUS itself. - New 'Deploying to Kubernetes' section covers running SUS for real on an existing cluster: prerequisites, Helm install, ingress exposure, first-run setup, and optional Authelia auth (folded in from the old Configuration subsections, which were really deployment concerns). Also add the second promo video (Authelia auth demo) to the Demo section, and fix cross-links (Configuration now points at the deploy subsections). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
Claude finished @dev-dull's task in 1m 28s —— View job Review: docs restructure (README split)
The split is the right call — the old "Quick Start" really was two audiences in one section, and separating Verified against the repo:
Two findings, both posted inline:
Out-of-diff nit, no action needed here: Otherwise this reads well and I'd merge it after #1. |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
| To run images you've built yourself (e.g. from a fork), push them to a registry your cluster can pull from and point the chart at them: | ||
|
|
||
| ```bash | ||
| git clone https://github.com/dev-dull/single-use-software.git | ||
| cd single-use-software | ||
| make build push | ||
| make build push # builds the landing + build-pod images | ||
| helm install sus ./charts/sus \ | ||
| --set landing.image.repository=your-registry/sus-landing \ | ||
| --set landing.image.tag=dev \ | ||
| --set buildPod.image.repository=your-registry/sus-build \ | ||
| --set buildPod.image.tag=dev \ | ||
| --set gitRepo.url=https://github.com/you/sus-starter-pack.git | ||
| ``` |
There was a problem hiding this comment.
make build push won't produce images at your-registry/... — the Makefile hardcodes the local k3d registry:
REGISTRY := localhost:5050
LANDING_IMAGE := $(REGISTRY)/sus-landing
BUILD_POD_IMAGE := $(REGISTRY)/sus-build
TAG := devSo following this block as written builds/pushes localhost:5050/sus-landing:dev (and push fails outright on a machine without the k3d registry running), then installs a chart pointing at your-registry/sus-landing:dev, which was never pushed → ImagePullBackOff.
Because these are :=, an env var won't override them either — it has to be a make command-line assignment:
| To run images you've built yourself (e.g. from a fork), push them to a registry your cluster can pull from and point the chart at them: | |
| ```bash | |
| git clone https://github.com/dev-dull/single-use-software.git | |
| cd single-use-software | |
| make build push | |
| make build push # builds the landing + build-pod images | |
| helm install sus ./charts/sus \ | |
| --set landing.image.repository=your-registry/sus-landing \ | |
| --set landing.image.tag=dev \ | |
| --set buildPod.image.repository=your-registry/sus-build \ | |
| --set buildPod.image.tag=dev \ | |
| --set gitRepo.url=https://github.com/you/sus-starter-pack.git | |
| ``` | |
| To run images you've built yourself (e.g. from a fork), push them to a registry your cluster can pull from and point the chart at them: | |
| ```bash | |
| git clone https://github.com/dev-dull/single-use-software.git | |
| cd single-use-software | |
| make build push REGISTRY=your-registry TAG=dev # builds + pushes the landing and build-pod images | |
| helm install sus ./charts/sus \ | |
| --set landing.image.repository=your-registry/sus-landing \ | |
| --set landing.image.tag=dev \ | |
| --set buildPod.image.repository=your-registry/sus-build \ | |
| --set buildPod.image.tag=dev \ | |
| --set gitRepo.url=https://github.com/you/sus-starter-pack.git |
(Nice catch adding the `buildPod.image.*` overrides, by the way — the old block only set `landing.image.*`, so build pods silently ran the GHCR image.)
| git clone https://github.com/dev-dull/single-use-software.git | ||
| cd single-use-software | ||
| make dev # creates a k3d cluster, builds images from source, and deploys the chart | ||
| kubectl port-forward -n sus svc/sus-landing 9090:80 |
There was a problem hiding this comment.
Minor: make dev finishes by printing its own hint using port 8080:
SUS is running. Access the landing page:
kubectl port-forward -n sus svc/sus-landing 8080:80
Both work, but now that this is the headline local-dev path, a user copying the README and then reading the terminal output gets two different ports. Worth making them agree (either port is fine — the Makefile echo is the easier one to change if 9090 is deliberate to avoid clashing with the ttyd port).
…ort, auth anchor Addresses the auto-review findings on #97: 1. The 'build your own images' snippet ran 'make build push', but the Makefile hardcodes REGISTRY := localhost:5050 (immediate assignment), so it would build/push to the k3d-local registry while the helm install pointed at your-registry/... -> ImagePullBackOff. Pass the override as a make command-line assignment: 'make build push REGISTRY=your-registry TAG=dev' (verified it resolves your-registry/sus-{landing,build}:dev). 2. 'make dev' echoed a 'port-forward ... 8080:80' hint, but host 8080 is already taken by the k3d loadbalancer (k3d.yaml maps 8080:80), and the README uses 9090. Point the Makefile echo at 9090 so they agree and the hint actually works. 3. Renamed the README auth heading back to 'Authentication (Authelia)' (optional-ness is already clear in the prose) so the existing references in charts/sus/values.yaml and templates/NOTES.txt still resolve; updated the two internal links to match. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
Claude finished @dev-dull's task in 2m 44s —— View job Review: docs restructure (round 2)
Both findings from the last round are fixed. Docs-only plus a one-line Prior findings — verified resolved:
Re-verified after the new commit:
One finding, posted inline (README.md:90, non-blocking): a reader who follows the "build your own images" Out-of-diff, no action needed here: README.md:216 tells operators using a non-Authelia proxy to Structure-wise this reads much better than the old single Quick Start. LGTM to merge; the inline note is optional polish. |
| git clone https://github.com/dev-dull/single-use-software.git | ||
| cd single-use-software | ||
| make build push | ||
| make build push REGISTRY=your-registry TAG=dev # builds + pushes the landing and build-pod images |
There was a problem hiding this comment.
The REGISTRY= fix is right — GNU make discards the makefile's REGISTRY := localhost:5050 when the variable is set on the command line, so the later LANDING_IMAGE := $(REGISTRY)/sus-landing expands to your-registry/sus-landing. Both images now get pushed and overridden. 👍
One leftover of the same class you just fixed for gitRepo.url: a reader who takes this path lands on 3. Expose it (Ingress), whose snippet is
helm upgrade sus oci://ghcr.io/dev-dull/charts/sus \
--set gitRepo.url=... --set ingress.enabled=true ...That switches the chart source back to the OCI chart and drops the four landing.image.* / buildPod.image.* overrides, so the next upgrade silently reverts to the GHCR images. One sentence closes it:
| make build push REGISTRY=your-registry TAG=dev # builds + pushes the landing and build-pod images | |
| make build push REGISTRY=your-registry TAG=dev # builds + pushes the landing and build-pod images |
…with a note added after the closing fence, e.g.:
If you go this route, carry the
--set landing.image.*/--set buildPod.image.*flags (and./charts/susinstead of the OCI URL) through thehelm upgradecommands in the sections below — otherwise the next upgrade reverts to the GHCR images.
Non-blocking; the mainline GHCR path is unaffected.
Addresses the #97 re-review's one non-blocking finding: a reader who builds their own images then follows the Ingress/Authentication 'helm upgrade oci://...' snippets would drop the --set image overrides and revert to the GHCR images — same class as the gitRepo.url footgun. Add a one-line note to the 'build your own images' block. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
Claude finished @dev-dull's task in 1m 12s —— View job Review: docs restructure (round 3)
The round-2 finding is fixed and I found nothing new. Still docs-only plus the one-line Prior finding — verified resolved:
Re-verified across the full PR:
One housekeeping item before merge (not a code issue): the PR description says the auth section was renamed to "Authentication (optional)" and lists Out-of-diff, no action needed here (repeating from round 2 so it isn't lost): README.md:216 tells operators using a non-Authelia proxy to set LGTM. No blocking findings. |
1 participant
Why
The README's "Quick Start" conflated two very different audiences: its prerequisites listed local-dev tooling (Docker, k3d) yet step 2 was a production
helm install oci://…. A homelabber trying to deploy SUS and a developer trying to hack on SUS were reading the same muddled section.What changed
Quick Start (local development)— now explicitly themake dev/ k3d path for evaluating and developing SUS itself. Prerequisites trimmed to the local-dev toolchain; adds agit clone → make dev → port-forwardflow and notes that an Anthropic key (via/setup) is only needed to actually build in a session.Deploying to Kubernetessection — the real deployment story for running SUS on an existing cluster (homelab k3s or managed EKS/GKE/AKS):helm installfrom GHCR (+ a<details>for building/pushing your own images)/setupand "build your first app".#ingressanchor is gone.Verification
#deploying-to-kubernetes,#3-expose-it-ingress,#authentication-authelia,#makefile-targets,#quick-start-local-development).Docs-only; no code or chart changes.
🤖 Generated with Claude Code
Update: kept the heading as Authentication (Authelia) (not renamed) so the existing
values.yaml/NOTES.txtcross-references stay valid; the review's port and registry-override findings are addressed in follow-up commits.