HexaField · HexaField · Oct 29, 2025 · Oct 29, 2025 · Oct 29, 2025 · Oct 29, 2025
diff --git a/.env.example b/.env.example
@@ -1,60 +1 @@
-# Shared Tailscale/Headscale settings used by both host app and k8s subnet router
-# For Headscale, set TS_LOGIN_SERVER to your Headscale URL and TS_AUTHKEY to a pre-auth key
-
-TS_LOGIN_SERVER=https://headscale.example.com
-TS_AUTHKEY=tskey-abc123
-TS_HOSTNAME=host-app
-ROUTER_HOSTNAME=host-app-router
-
-# Advertised routes from k8s Tailscale subnet router (k8s + Service/Pod CIDRs)
-TS_ROUTES=10.0.0.0/24,10.96.0.0/12,10.244.0.0/16
-
-# Optional org identifier used by the registry endpoints
-ORG_ID=default
-
-# Optional aliases
-HEADSCALE_URL=
-HEADSCALE_AUTHKEY=
-
-# Full-cluster deploy coordinates (used by setup-k8s scripts)
-# If not provided, sensible defaults are used.
-CLUSTER=mycluster
-ENDPOINT=https://10.0.0.10:6443
-CP_NODES=10.0.0.10
-WK_NODES=10.0.0.20
-
-# Kubeconfig location (used by scripts and Makefile)
 GN_KUBECONFIG=$HOME/.guildnet/kubeconfig
-
-# Preflight + auto-heal tuning (k8s setup)
-PRECHECK_PORT=50000
-PRECHECK_TIMEOUT=3
-PRECHECK_MAX_WAIT_SECS=600
-PRECHECK_PING=0
-REQUIRE_ENDPOINT_MATCH_CP=0
-APPLY_RETRIES=10
-APPLY_RETRY_DELAY=5
-KUBE_READY_TRIES=90
-KUBE_READY_DELAY=5
-
-# Database (RethinkDB) setup toggle and service info
-# RethinkDB must run inside the Kubernetes cluster. The Host App
-# expects an in-cluster service (ClusterIP/LoadBalancer/NodePort). Do not
-# configure a local loopback address for RethinkDB.
-RETHINKDB_SERVICE_NAME=rethinkdb
-RETHINKDB_NAMESPACE=
-
-# Kubernetes options
-K8S_NAMESPACE=default
-K8S_IMAGE_PULL_SECRET=regcreds
-
-# Optional registry credentials for creating pull secret (scripts/k8s-setup-registry-secret.sh)
-# DOCKER_SERVER=docker.io
-# DOCKER_USER=your-username
-# DOCKER_PASS=your-password-or-token
-# DOCKER_EMAIL=you@example.com
-
-# Local dev helpers
-# WORKSPACE_DOMAIN=workspaces.127.0.0.1.nip.io
-# INGRESS_CLASS_NAME=nginx
-# CERT_MANAGER_ISSUER=
diff --git a/AGENTS.md b/AGENTS.md
@@ -12,6 +12,10 @@ Always ensure everything the user asks to be done is actually done, even if it r
 
 Before asking the user to choose from an option, automatically go with the simplest option and keep going until the problem is solved.
 
-ALWAYS update API.md, architecture.md and DEPLOYMENT.md with any relevant changes.
+ALWAYS update API.md, architecture.md and DEPLOYMENT.md with any relevant changes without duplicating information.
+
+Always update planning docs with progress on tasks.
+
+Do not leave deprecated code or comments in the codebase. Remove any code that is no longer needed.
 
 Use /tmp for temporary files, never the project directory.
diff --git a/API.md b/API.md
diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md
diff --git a/Makefile b/Makefile
@@ -10,8 +10,8 @@ LISTEN_LOCAL ?= 127.0.0.1:8090
 # User-scoped kubeconfig location (used by scripts and docs)
 GN_KUBECONFIG ?= $(HOME)/.guildnet/kubeconfig
 
-# Provisioner choice: lan | forward | vm
-PROVIDER ?= lan
+# Provisioner choice kept for future use; MicroK8s is the only supported local cluster
+PROVIDER ?= microk8s
 
 .PHONY: all help \
 	build build-backend build-ui \
@@ -21,7 +21,7 @@ PROVIDER ?= lan
 	agent-build \
 	crd-apply operator-run operator-build db-health \
 	setup-headscale setup-tailscale setup-all \
-	# Local disposable cluster helper removed; use microk8s or set KUBECONFIG
+	# Local disposable cluster helper removed; use MicroK8s helpers or set KUBECONFIG
 	deploy-k8s-addons deploy-operator deploy-hostapp verify-e2e \
 	diag-router diag-k8s diag-db headscale-approve-routes
 multi-device-host: ## One-command bootstrap of Device A (Headscale+cluster+operator+Host App)
@@ -90,25 +90,19 @@ setup-headscale: ## Setup Headscale (Docker) and bootstrap preauth
 setup-tailscale: ## Setup Tailscale router (enable forwarding, up, approve routes)
 	bash ./scripts/setup-tailscale.sh
 
-setup-all: ## One-command: Headscale up -> LAN sync -> ensure Kubernetes (microk8s) -> Headscale namespace -> router DS -> addons -> operator -> hostapp -> verify
+setup-all: ## One-command: Headscale up -> LAN sync -> ensure MicroK8s -> Headscale namespace -> router DS -> addons -> operator -> hostapp -> verify
 	@CL=$${CLUSTER:-$${GN_CLUSTER_NAME:-default}}; \
 	echo "[setup-all] Using cluster: $$CL"; \
 	$(MAKE) headscale-up; \
 	$(MAKE) env-sync-lan; \
-	# Ensure Kubernetes is reachable; if not, try microk8s setup or fail
+	# Ensure Kubernetes is reachable; if not, bring up MicroK8s
 	ok=1; kubectl --request-timeout=3s get --raw=/readyz >/dev/null 2>&1 || ok=0; \
-	if [ $$ok -eq 0 ]; then \
-		# Attempt microk8s setup if helper script exists
-		if [ -x "./scripts/microk8s-setup.sh" ]; then \
-			bash ./scripts/microk8s-setup.sh $(GN_KUBECONFIG) || { echo "microk8s setup failed"; exit 2; }; \
-		else \
-			echo "Kubernetes API not reachable; please configure KUBECONFIG or install microk8s"; exit 2; \
-		fi; \
-	fi; \
+	if [ $$ok -eq 0 ]; then bash ./scripts/microk8s-up.sh || true; fi; \
 	CLUSTER=$$CL $(MAKE) headscale-namespace; \
 	CLUSTER=$$CL $(MAKE) router-ensure || true; \
 	$(MAKE) deploy-k8s-addons || true; \
 	$(MAKE) deploy-operator || true; \
+	$(MAKE) ensure-operator-setup || true; \
 	$(MAKE) deploy-hostapp || true; \
 	$(MAKE) verify-e2e || true
 
@@ -127,10 +121,10 @@ operator-image-build: build-backend ## Build a container image for the operator
 	@echo "Building operator image $(OPERATOR_IMAGE) ..."
 	docker build -f scripts/Dockerfile.operator -t $(OPERATOR_IMAGE) .
 
-operator-image-load: operator-image-build ## Load the operator image into a local cluster (microk8s preferred)
-	@echo "Loading operator image into local cluster (microk8s preferred)"
-	# Delegate to helper script which handles microk8s image import
-	@bash ./scripts/load-operator-image.sh $(OPERATOR_IMAGE) "" || echo "operator image load helper failed"
+operator-image-load: operator-image-build ## Ensure operator image is available to your cluster
+	@echo "Operator image built: $(OPERATOR_IMAGE)"
+	@echo "Tip: prefer pushing to a registry accessible by the cluster (e.g., GHCR, Docker Hub)."
+	@echo "If using MicroK8s, ensure your nodes can pull the image (or use a local registry)."
 
 operator-build-load: operator-image-load ## Convenience target to build and load operator image
 	@echo "operator image build+load complete"
@@ -181,9 +175,8 @@ reset: ## Full reset: stop hostapp, headscale, tailscale, delete test clusters,
 	@echo "[reset] Bringing down Tailscale router (if configured)";
 	@$(MAKE) router-down || true
 	@echo "[reset] Running cleanup script to remove local state under ~/.guildnet (if present)";
-	@bash ./scripts/cleanup.sh --all || true
-	@echo "[reset] Removing local GN_KUBECONFIG file: $(GN_KUBECONFIG) (if present)";
-	@if [ -f "$(GN_KUBECONFIG)" ]; then rm -f "$(GN_KUBECONFIG)" && echo "  removed $(GN_KUBECONFIG)"; else echo "  not found: $(GN_KUBECONFIG)"; fi
+	@bash ./scripts/cleanup.sh --all || true; \
+	if [ -f "$(GN_KUBECONFIG)" ]; then rm -f "$(GN_KUBECONFIG)" && echo "  removed $(GN_KUBECONFIG)"; else echo "  kubeconfig not found: $(GN_KUBECONFIG)"; fi
 	@echo "[reset] Removing temporary headscale/router cluster files in tmp/ (if present)";
 	@rm -f tmp/cluster-*-headscale.json tmp/cluster-*-kubeconfig || true
 	@echo "[reset] Completed. Some resources (e.g., cluster objects on remote K8s, remote Tailscale state) may remain and require manual cleanup.";
@@ -281,16 +274,18 @@ headscale-approve-routes: ## Approve tailscale routes for the router in Headscal
 export KUBECONFIG := $(GN_KUBECONFIG)
 
 # ---------- Provision / Addons / Deploy / Verify ----------
-.PHONY: deploy-k8s-addons deploy-operator deploy-hostapp verify-e2e diag-router diag-k8s diag-db
+.PHONY: deploy-k8s-addons deploy-operator deploy-hostapp verify-e2e diag-router diag-k8s diag-db verify-operator smoke-workspace ensure-operator-setup microk8s-up microk8s-down
 
 deploy-k8s-addons: ## Install MetalLB (pool from .env), CRDs, imagePullSecret, DB
+	bash ./scripts/install-local-path-provisioner.sh || true
 	bash ./scripts/deploy-metallb.sh
 	$(MAKE) crd-apply
 	bash ./scripts/k8s-setup-registry-secret.sh || true
 	bash ./scripts/rethinkdb-setup.sh || true
 
+
 deploy-operator: ## Deploy operator (ensure operator image is available, then apply manifests)
-	# If you use microk8s for local development, import the operator image first with: make operator-image-load
+	# Ensure the operator image is accessible to your cluster (push to a registry if needed)
 	bash ./scripts/deploy-operator.sh
 
 deploy-hostapp: ## Run hostapp locally (or deploy in cluster if configured)
@@ -315,6 +310,25 @@ diag-k8s: ## Show kube API status and nodes
 diag-db: ## Print DB service details
 	bash ./scripts/rethinkdb-setup.sh || true
 
+microk8s-up: ## Bring up MicroK8s and write kubeconfig to $(GN_KUBECONFIG)
+	bash ./scripts/microk8s-up.sh
+
+microk8s-down: ## Tear down MicroK8s (see script for options)
+	bash ./scripts/microk8s-down.sh
+
+verify-operator: ## Verify CRDs and operator are installed and running
+	bash ./scripts/verify-crds-operator.sh
+
+.PHONY: verify-storage
+verify-storage: ## Verify default StorageClass and RethinkDB PVC readiness
+	bash ./scripts/verify-storage.sh
+
+smoke-workspace: ## Apply a tiny Workspace CR from template (idempotent)
+	bash ./scripts/smoke-workspace.sh
+
+ensure-operator-setup: ## Ensure operator-config/certs and patch operator Deployment on current cluster
+	bash ./scripts/k8s/ensure-operator-setup.sh
+
 .PHONY: diag-multi-device
 diag-multi-device: ## Summarize multi-device status (operator, CRDs, router, health)
 	bash ./scripts/diag-multi-device.sh
@@ -404,6 +418,15 @@ router-ensure: ## Deploy Tailscale subnet router DaemonSet (uses tmp/cluster-<id
 plain-quickstart: ## Alias to setup-all for plain K8S flow
 	$(MAKE) setup-all
 
+# ---------- MicroK8s helpers ----------
+.PHONY: microk8s-up microk8s-down
+
+microk8s-up: ## Bring up MicroK8s and write kubeconfig
+	bash ./scripts/microk8s-up.sh
+
+microk8s-down: ## Tear down MicroK8s (reset/stop/remove)
+	bash ./scripts/microk8s-down.sh
+
 .PHONY: deploy-networkpolicies
 deploy-networkpolicies: ## Apply recommended network policies for workspace isolation
 	@echo "Applying networkpolicies..."
@@ -412,3 +435,5 @@ deploy-networkpolicies: ## Apply recommended network policies for workspace isol
 	else \
 		echo "Kubernetes API not reachable; skipping networkpolicies"; \
 	fi
+
+# (DinD helpers removed; prefer using a registry or MicroK8s-compatible image workflows.)
diff --git a/README.md b/README.md
@@ -30,6 +30,26 @@ GuildNet is a private self-hostable stack that puts human-in-the-loop with agent
 
 ## Quickstart
 
+### Local cluster (MicroK8s)
+
+The default local path uses MicroK8s as the Kubernetes distribution:
+
+- Bring up MicroK8s and emit kubeconfig (optionally expose kube-API over the tailnet):
+  - `scripts/microk8s-up.sh`
+  - Expose kube-API over tailnet (optional): `TS_AUTHKEY=tskey-... TS_LOGIN_SERVER=http://<headscale>:8081 make ts-serve-kubeapi`
+- Install addons/CRDs/DB and deploy the operator:
+  - `make deploy-k8s-addons`
+  - `make deploy-operator`
+  - Ensure operator config/certs and patch Deployment: `make ensure-operator-setup`
+- Attach cluster to the Host App:
+  - Use the UI to "Download join config" and POST it to `/api/bootstrap`, or
+  - Generate locally: `make generate-join-config` (writes `guildnet.config`) and POST it to the HostApp `/api/bootstrap` endpoint.
+
+Verification:
+
+- Verify Kubernetes API and nodes: `make diag-k8s`
+- Verify end-to-end (headscale, router, kube API, DB): `make verify-e2e`
+
 ### Headscale
 Start or use Headscale as your Tailnet controller and create a reusable pre-auth key (local helper: `make headscale-up` and `make headscale-bootstrap`).
 
@@ -48,15 +68,7 @@ Verification:
 - Ensure local tailscaled / router is running: `make router-daemon` or check status with `make router-status`
 - Verify routes are approved and visible in Headscale: `make headscale-approve-routes`
 
-### Deploy cluster
-
-
-Create or point to a Kubernetes cluster. For local development we recommend `microk8s` (use `bash ./scripts/microk8s-setup.sh` which writes a kubeconfig to `$(GN_KUBECONFIG)`). After the cluster is ready install addons and RethinkDB with `make deploy-k8s-addons` and deploy the operator with `make deploy-operator`.
-
-Verification:
 
-- Verify Kubernetes API connectivity & nodes: `make diag-k8s`
-- Verify deployed addons and operator reconciliation: `make verify-e2e`
 
 ### Launch Host App server
 
@@ -71,19 +83,19 @@ Verification:
 ### Connect from another device
 
 
-From any device on the Tailnet open the Host App URL (https://localhost:8090), use the cluster Settings to "Download join config" and transfer that `guildnet.<cluster>.config` to another Host App instance or POST it to `/bootstrap` to register the cluster.
+From any device on the Tailnet open the Host App URL (https://localhost:8090), use the cluster Settings to "Download join config" and transfer that `guildnet.<cluster>.config` to another Host App instance or POST it to `/api/bootstrap` to register the cluster.
 
 Verification:
 
 - Generate a join config locally (same format the UI emits): `make generate-join-config` (writes `guildnet.config` by default)
-- Register a joiner by POSTing the config to the host app (server must be reachable): `curl -k -X POST https://<hostapp>:8090/bootstrap -H 'Content-Type: application/json' --data @guildnet.config`
+- Register a joiner by POSTing the config to the host app (server must be reachable): `curl -k -X POST https://<hostapp>:8090/api/bootstrap -H 'Content-Type: application/json' --data @guildnet.config`
 
 ### Participate in a cluster
 
 Short flow (federated / multi-device):
 
 - Device A (host): run the Host App and ensure Headscale + cluster/operator are set up (quick helpers: `make multi-device-host`).
-- Device B (joiner): generate a join config (`make generate-join-config`) and either use the Host App UI "Download join config" on Device A or POST the generated `guildnet.config` to Device A's `/bootstrap` endpoint to register the device. There is also a helper target `make multi-device-joiner` for an automated joiner flow.
+- Device B (joiner): generate a join config (`make generate-join-config`) and either use the Host App UI "Download join config" on Device A or POST the generated `guildnet.config` to Device A's `/api/bootstrap` endpoint to register the device. There is also a helper target `make multi-device-joiner` for an automated joiner flow.
 
 Notes: