5d3600845d
Brings up the smallest k3d-resident stack that lets a host-side knoe-auth
(run via `mvn spring-boot:run` or IntelliJ) iterate against real Postgres
+ Kerberos. Closes Phase 1 of the k3d-gke-mirror plan (docs/plans/k3d-gke-mirror.md).
Scope:
- k8s/knoe/knoe-kdc-{configmap,deployment,service,pvc,init-job}.yaml
NEW; standalone KDC, realm KNOE.LOCAL (distinct from KNOE.DEV).
- etc/init_knoe_auth.sh: --mode k3d flag added; swaps realm + skips
GCP-specific steps. GKE behavior unchanged when flag absent.
- Makefile: k3d-knoe-up, k3d-knoe-pf, k3d-knoe-down (delegate to
scripts/k3d-knoe-{up,pf,down}.sh).
- scripts/k3d-knoe-{up,pf,down,smoke}.sh NEW; up = full bring-up,
pf = three port-forwards (5432/88/464) + JDBC URL + ^C cleanup,
down = teardown, smoke = sanity check.
- etc/krb5.local.conf NEW; checked-in libdefaults+realms config
pointing at localhost:88. udp_preference_limit=1 to dodge
kubectl port-forward UDP flakiness on macOS.
- docs/local-dev-knoe-auth.md NEW; one-time setup + daily loop +
IntelliJ run config.
- docs/knoe-system.md NEW; unified reference for the knoe-auth
service (GKE deployment + k3d dev loop + schema overview +
source map + open work items).
Verified per the brief's Definition of done: fresh-clone laptop can
`make k3d-knoe-up` + `make k3d-knoe-pf` + `mvn -pl authority spring-boot:run`
and hit /health, /.well-known/openid-configuration in <8 minutes.
Out of scope (parent plan docs/plans/k3d-gke-mirror.md §6):
- SPNEGO from host browsers (Phase 2)
- knoe-auth-as-pod / image build/load (Phase 3)
- Supabase stack on k3d (Phase 4)
- OidcCodeService DB persistence (separate track)
docs/plans/junie/README.md — k3d brief moved from Active to Shipped.
docs/TODO.md — In-progress now empty; Phase 2 pg_oauth notes that the
local dev loop is in place so it can resume.
Closes Phase 1; Phase 2+ briefs filed as needed.
Co-authored-by: Junie <junie@jetbrains.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
||
|---|---|---|
| .. | ||
| junie | ||
| customer-deploy-resync.md | ||
| deployment-modes.md | ||
| k3d-gke-mirror.md | ||
| knoe-auth-round-1.md | ||
| onboarding-tdd-phase-a.md | ||
| onboarding-tdd.md | ||
| README.md | ||
Plans
Engineering plans for the knoe.dev platform. Each document scopes one initiative — its strategic context, design, schema, and the components it adds — and is intended to outlive the implementation work itself: when the work ships, the plan stays as the architectural reference.
Who this is for
You are a junior or mid-level engineer who has been invited to contribute to knoe.dev. These documents are written for you. They assume:
- You are comfortable reading code and skimming a Maven
pom.xml. - You have used Kubernetes at least casually (
kubectl get pods, helm charts). - You may not have prior Kerberos, OIDC, or CNPG experience — relevant terms are defined inline or in the glossary section of each plan.
- You have not seen this repo before. Each plan starts with the strategic context and links to existing code before it asks you to write any.
If a sentence in a plan assumes knowledge you don't have, that's a bug in the plan — open an issue.
What lives here
| File | Initiative | When you should read it |
|---|---|---|
knoe-auth-round-1.md |
Identity backbone for the platform: MIT Kerberos KDC + invite-anchored web enrollment + TOTP 2FA. Round 1 of N. Shipped. | Before touching authority/, etc/init_kdc.sh, etc/init_knoe_users.sh, anything in deploy/gcp/gke/knoe-auth-* or knoe-kdc-*, or the knoe.* database schema. |
deployment-modes.md |
Four-mode installer (min / k3d / k3s / gke) with a welcome-screen mode selector and a min-mode fast-path through the wizard. Shipped in Phase 0. |
Before touching knoe/ui/screens/welcome.py, knoe/ui/screens/navigation.py, or adding any new wizard screen. |
k3d-gke-mirror.md |
Laptop-resident model of the GKE platform — minimum-viable k3d stack (CNPG + KDC) that lets host-side knoe-auth iterate against real Postgres + Kerberos. Active. Phase 1 in flight (Junie). | Before touching k8s/knoe/knoe-kdc-*, the make k3d-knoe-* targets, or docs/local-dev-knoe-auth.md. Phase 1 brief at junie/k3d-knoe-auth-dev-loop.md. |
customer-deploy-resync.md |
Original plan to converge ~/dev/prole onto knoe-db/main as a customer-deploy branch. Dormant — prole rebrand merged into main; no separate prole working tree currently under development. |
Only if you're considering activating a per-customer branching workflow. |
junie/ (subdirectory) |
Self-contained, single-task work briefs for Junie to consume from inside the IDE. Tactical, single-MR scope, paired against numbered items in ../TODO.md. |
When you want to hand a discrete task to Junie or audit what's been queued. |
../TODO.md (sibling) |
Master TODO index — single source of truth for unfinished work, including reality-vs-intent gaps flagged in CLAUDE.md/AGENTS.md. |
Before picking up any task, to see what's already on the queue. |
Each plan follows the same shape: Context → How it's wired (file references) → Architecture → Schema / API → Step-by-step → Verification → Glossary.
Status conventions
A plan in this directory has one of three statuses, declared at the top:
- Active plan. Not yet implemented. — the design is agreed, the code isn't there yet. Read deliverables top-to-bottom.
- Implemented and operational. Architectural reference. — the work shipped. The doc explains how it works and why; cross-references point at real files. Read the context and the rationale; jump to specific sections when you have a question.
- Archived. — superseded by a later round or a different approach. Lives in
archive/with a one-line "see X instead" pointer.
Customer deploys
The knoe.dev platform is designed to support per-customer deployments via branches in this repo, not separate forks. Customer-specific divergence (config, branding, on-prem manifests, kubeconfig handling) would live on a branch named after the customer; platform changes always land on main and customer branches rebase or merge from main on a regular cadence.
Currently no customer branch is active. The original plan to converge ~/dev/prole into a customer/prole.org branch is captured in customer-deploy-resync.md and is dormant — the prole→knoe rebrand has merged into main itself, and there is no separate ~/dev/prole working tree under development. origin and knoe remotes both point at upstream git@git-ssh.knoe.dev:knoe.dev/knoe-db.git.
How to propose a new plan
- Copy
knoe-auth-round-1.mdas a template — the section structure is the convention. - Lead with why (one or two paragraphs). Half the value of a plan is forcing the author to articulate the motivation.
- Cite real files with paths relative to the repo root. If you reference something that doesn't exist yet, label it (net-new) so a reader doesn't go hunting.
- End with a Verification section — a short checklist a reviewer can run to decide whether the plan is done, or — once shipped — that the implementation still matches the spec.
- Open an MR. Plans are reviewed like code.