prole/docs/plans/deployment-modes.md

# Deployment Modes — Welcome Screen + Wizard Fast-Path

**Status:** Implemented and operational. Architectural reference. Welcome-screen mode selector and `min`-mode fast-path shipped in Phase 0.
**Owner:** chrisfu
**Audience:** Jr/mid engineer onboarding to knoe.dev. Familiarity with Tk/tkinter helps but is not required.

---

## 1. Context

The knoe-db installer (`./install.sh` / `./knoe.sh install`, driven by the Tk UI in `knoe/ui/screens/`) supports four ways to deploy the platform. Different audiences, different hardware, but **the same architecture underneath**.

Earlier installer revisions assumed the engineer already knew which mode they wanted, presented a welcome screen that was a wall of text, and shipped a sidebar tab strip (`k3d` / `k3s` / `k8s`) that didn't reliably refresh state across screens. Phase 0 replaced all of that with a first-screen mode selector that teaches the engineer what each mode *is* before asking them to choose, and added a `min`-mode fast-path that skips wizard screens irrelevant to a single-container deployment.

### The four modes

| Mode | What it is | Who it's for | Required tools |
| --- | --- | --- | --- |
| **min** | A single `knoe-db` container under `containerd` — no Kubernetes, no Docker. The Spring Boot app runs locally on the host. | Engineers running a Spring app on a laptop and wanting a CNPG-compatible Postgres without a full cluster. | Homebrew, 1Password |
| **k3d** | A Docker-based local k3s cluster. Full CNPG + optional Supabase / ArgoCD / Gitea / GitLab. | Local development with the full platform. | Docker, Homebrew, 1Password |
| **k3s** | A multi-node k3s cluster on real hardware. Full Kerberos auth stack, Garage S3, monitoring. Mirrors the GKE shape. | Homelab contributors with their own hardware (e.g. a 3-node Pi cluster). | k3sup, Homebrew, 1Password |
| **gke** | The production dual-cluster on Google Cloud (`knoe-dev-0` + `knoe-dev-cnpg-0` in `us-west3`). | Production. | gcloud, kubectl, 1Password |

The architectural commitment matters: **all four modes are scaled-down mirrors of the GKE shape.** Not parallel implementations of the same idea, not divergent forks — the same components composed at different scales. CNPG runs in all four. The Spring Boot `authority` service runs in all four. `knoe.user` lives in the same schema in all four. The only thing that changes is what platform the components run on and which optional services are enabled.

### Mode → cluster_env mapping

| `cluster_env` | `KNOE_MODE` | Target |
| --- | --- | --- |
| `dev` | `k3d` | Local K3d cluster |
| `service` | `k3s` | On-prem K3s cluster |
| `prod` | `k8s` (alias `gke`) | GKE (or other cloud) |
| `min` | `min` | Local containerd (no Kubernetes) |

The conversion lives in `knoe/core/env.py` (`_deployment_mode_from_env()`).

### Config file mapping

`knoe/knoe_conf.py` maps environments to config files under `conf/`:

| Mode | Config file |
| --- | --- |
| `min` | `conf/min.cfg` |
| `k3d` (`dev`) | `conf/k3d.cfg` |
| `k3s` (`service`) | `conf/k3s.cfg` |
| `gke` (`prod`) | `conf/gke.cfg` |

Config is layered: env-specific file overrides base. `KNOE_CONF` env var or `conf/service/` subdirs point to the active config.

---

## 2. How it's wired — file map

| Component | Location | What's there |
| --- | --- | --- |
| Welcome screen with mode selector | `knoe/ui/screens/welcome.py` | `WelcomeScreenMixin._render_welcome_page()` renders the four mode cards. Click handler updates `deployment_mode` and `cluster_env`, redraws card borders, re-evaluates the Next gate. |
| Sidebar nav | `knoe/ui/screens/navigation.py` | `_create_sidebar_nav()` no longer renders the old `k3d/k3s/k8s` tab strip — the welcome card selector replaces it. `_set_deployment_mode` is still called from the welcome handler. |
| Mode/state initialization | `knoe/ui/screens/__init__.py` | `nav_items` list, `deployment_mode = tk.StringVar(...)`, `cluster_env = tk.StringVar(...)`. |
| Wizard transitions | `knoe/ui/screens/navigation.py` `on_next` / `on_prev` | Min-mode fast-path skips screens that don't apply (network scan, cluster init, Kerberos, ArgoCD, Supabase, common services). |
| Update-footer Next-button gate | `knoe/ui/screens/navigation.py` `update_footer` | Welcome screen disables Next until a mode is selected. |
| Min-mode bootstrap | `etc/init_min.sh` | Idempotent: ensures Homebrew + containerd, pulls and runs the `knoe-db` container locally, runs schema bootstrap, prints connection info. Invoked from `init_scripts` step in min mode. |
| Min-mode config | `conf/min.cfg` | Modeled on `conf/k3d.cfg`. Just what `init_min.sh` needs. |
| Min-mode lifecycle | `knoe.sh` (`start` / `stop` / `restart` subcommands) | Manages the local containerd `knoe-db` instance for users who don't want to run the wizard every time. |

---

## 3. UI layout — welcome screen

```
┌──────────────────────────────────────────────────────────────────┐
│                                                                  │
│                                       knoe.dev                   │
│                                       infrastructure.auto()      │
│                                                                  │
│   Welcome                                                        │
│   ───────                                                        │
│   Knoe.DB sets up a production-grade PostgreSQL cluster with     │
│   Kerberos authentication. Pick the mode that matches your       │
│   hardware — we'll walk you through every step.                  │
│                                                                  │
│   ┌────────────┬────────────┬────────────┬────────────┐          │
│   │  min       │  k3d       │  k3s       │  gke       │          │
│   │  Just a    │  Local     │  Homelab   │  Production│          │
│   │  Database  │  Cluster   │            │            │          │
│   │ One knoe-db│ k3s-in-    │ Multi-node │ Dual GKE   │          │
│   │ container  │ Docker     │ k3s on real│ clusters on│          │
│   │ via        │ cluster on │ hardware.  │ Google     │          │
│   │ containerd.│ your Mac.  │ Full       │ Cloud.     │          │
│   │ No K8s.    │ Full CNPG  │ Kerberos   │ CNPG +     │          │
│   │ Perfect for│ database — │ auth stack,│ GCS backups│          │
│   │ a Spring   │ add        │ Garage S3, │ + Workload │          │
│   │ app on your│ Supabase,  │ monitoring.│ Identity.  │          │
│   │ laptop.    │ ArgoCD,    │            │            │          │
│   │            │ Gitea, or  │            │            │          │
│   │            │ GitLab.    │            │            │          │
│   │ Homebrew + │ Docker +   │ k3sup +    │ gcloud +   │          │
│   │ 1Password  │ Homebrew + │ Homebrew + │ 1Password  │          │
│   │            │ 1Password  │ 1Password  │            │          │
│   └────────────┴────────────┴────────────┴────────────┘          │
│                                                                  │
│   You'll need: Docker · Homebrew · 1Password                     │
│                                                                  │
│                                          [   Next →  ]           │
└──────────────────────────────────────────────────────────────────┘
```

Behavior:

- The four cards are clickable.
- The selected card gets a colored border in the mode's accent color (`_MODE_COLORS`: `min` purple, `k3d` blue, `k3s` green, `gke` orange).
- The "You'll need:" line below the cards updates to reflect the selected mode's tools.
- The Next button is **disabled** until a mode is selected.
- Selecting a card also sets `cluster_env` via the mode-to-cluster_env map.
- On Next, mode is persisted to `knoe_cfg_data["Global"]["DEPLOYMENT_MODE"]`.

---

## 4. Wizard transitions — `min`-mode fast-path

### Default flow (k3d / k3s / gke)

```
welcome → network_scan → env_setup → init_cluster → cluster_nodes →
init_password → init_scripts → kerberos_config → knoe_users →
argocd_config → gitops_config → supabase_config → common_services →
… → security
```

### Min-mode flow

```
welcome → dependencies → environment → init_password → init_scripts → security
```

Skipped in min: `network_scan`, `init_cluster`, `cluster_nodes`, `kerberos_config`, `knoe_users`, `argocd_config`, `gitops_config`, `supabase_config`, `common_services`. None of them apply when there's no Kubernetes cluster and no Kerberos KDC. `init_scripts` invokes `etc/init_min.sh` instead of the cluster-mode init scripts.

The fast-path is implemented as a `_min_mode_next` dictionary in `knoe/ui/screens/navigation.py` consulted from `on_next` / `on_prev`. The override is only active when `_is_min_mode()` returns true.

---

## 5. Verification

Run after any change touching the wizard or mode logic.

1. `./install.sh` opens. The welcome screen shows four mode cards. The sidebar has **no** k3d/k3s/k8s tab strip.
2. With no mode selected, the Next button is disabled.
3. Click the **min** card. Next becomes enabled. Click Next.
   - The wizard skips the network-scan screen.
   - It skips `init_cluster` and `cluster_nodes`.
   - It skips `kerberos_config`, `knoe_users`, `argocd_config`, `gitops_config`, `supabase_config`, `common_services`.
   - It runs `init_min.sh` at the `init_scripts` step.
   - It lands on the `security` screen.
   - Going back through `on_prev` walks the same trimmed sequence in reverse without hitting any skipped screens.
4. Click the **k3d** card on a fresh run. The wizard follows the existing k3d flow exactly as before.
5. `python3 -c "from knoe.ui.screens import KnoeInstaller"` — no import errors.
6. After completing min mode, `nerdctl ps` shows the `knoe-db` container running locally and `psql "${printed_conn_string}" -c '\dt knoe.*'` lists the `knoe.user` table.
7. `./knoe.sh stop` and `./knoe.sh start` cleanly stop/restart the local containerd instance.

---

## 6. Out of scope

- A `min`-mode equivalent of the full Kerberos auth stack. Min is "just a database". Auth in min is a follow-up.
- Migrating an existing `k3d` deployment to `min` (or any other mode-to-mode migration). Each mode is an independent target.
- A unified package format that produces all four mode-specific installers from one `pyinstaller` build. The current per-mode build is fine.
- Letting one wizard run install *multiple* modes (e.g. set up `k3d` and `gke` from the same session). One mode per run.

---

## 7. Glossary

**k3s** — A lightweight Kubernetes distribution by Rancher Labs. Single binary, runs comfortably on a Raspberry Pi. The same project, two delivery shapes: `k3d` is k3s wrapped in Docker; bare k3s is k3s on actual hardware.

**k3d** — A wrapper that runs k3s clusters inside Docker containers. Useful for local dev because it gives you a "real" Kubernetes cluster without having to provision VMs.

**GKE (Google Kubernetes Engine)** — Google Cloud's managed Kubernetes. We use Standard for `knoe-dev-0` and `knoe-dev-cnpg-0`. See `CLAUDE.md` for cluster topology.

**containerd** — A container runtime. Speaks the OCI image and runtime specs. Both Docker and Kubernetes use containerd under the hood. In `min` mode we talk to it directly via `nerdctl`, skipping Docker entirely.

**nerdctl** — A Docker-CLI-compatible client for `containerd`. If you know `docker run`, you know `nerdctl run`.

**CNPG (CloudNativePG)** — The Postgres operator we use for `knoe-db`. See `CLAUDE.md` for which cluster runs it in production.

**`cluster_env`** — A label the installer carries internally that picks which `conf/*.cfg` file to read and which downstream config branches to take. Maps from `deployment_mode` per the table in §1. Don't reuse this name for new variables — it's already overloaded enough.

**Tk / tkinter** — Python's standard GUI toolkit. The installer is built on it. Canvas-based rendering means we draw text and shapes directly rather than using Tk's widget hierarchy for the welcome screen.

**Wizard / pid** — The installer is a multi-screen wizard. Each screen has a "page id" (`pid`) — `welcome`, `network_scan`, `init_cluster`, etc. `nav_items` is the ordered list; `on_next` / `on_prev` decide transitions based on the current `pid` and the user's state.