Updated readme with diagram describing design

README.md

@@ -2,6 +2,60 @@
 
 This repository manages home-lab services through two delivery paths: existing host Compose stacks and a Talos Kubernetes cluster reconciled by Argo CD.
 
+```mermaid
+flowchart LR
+  developer[Developer workstation]
+  repo[Gitea repository<br/>whentimeslows/home-services]
+
+  subgraph compose[Compose delivery path]
+    actions[Gitea Actions]
+    nas[Self-hosted runner: nas1]
+    rhel[Self-hosted runner: rhel1]
+    nasStack[compose-services/media_nas1<br/>Docker Compose]
+    rhelStack[compose-services/media_rhel1<br/>Podman Compose]
+    actions --> nas --> nasStack
+    actions --> rhel --> rhelStack
+  end
+
+  subgraph bootstrap[Terraform bootstrap path]
+    terraform[Terraform]
+    secrets[Talos machine secrets]
+    talosConfig[Role-specific Talos machine configuration]
+    terraform --> secrets
+    terraform --> talosConfig
+  end
+
+  subgraph cluster[Talos Kubernetes cluster]
+    cp[Control-plane nodes]
+    workers[Worker nodes]
+    argocd[Argo CD]
+    appsets[ApplicationSets]
+    apps[Generated Applications]
+    workloads[Cluster workloads]
+    cp --> argocd
+    workers --> workloads
+    argocd --> appsets --> apps --> workloads
+  end
+
+  subgraph gitops[GitOps repository directories]
+    appsetFiles[bootstrap/applicationsets]
+    infra[infrastructure/*<br/>Cilium and Longhorn charts]
+    services[services/*<br/>Vaultwarden and other charts]
+    appsetFiles -. registers .-> appsets
+    infra --> apps
+    services --> apps
+  end
+
+  developer -->|pushes code| repo
+  repo -->|workflow checkout| actions
+  repo -->|Terraform source and chart source| terraform
+  terraform -->|configures and bootstraps| cluster
+  repo -->|Git polling or webhook| argocd
+  developer -->|kubectl handoff| appsetFiles
+```
+
+The Compose path deploys host services through Gitea Actions. The GitOps path uses Terraform for Talos day-zero bootstrap, then Argo CD pulls chart definitions from Gitea and continuously reconciles Kubernetes resources. The `bootstrap/applicationsets/` manifests are the initial handoff between Terraform-installed Argo CD and the GitOps repository.
+
 ## Repository layout
 
 ```text
@@ -71,11 +125,30 @@ The `up` operation avoids an unnecessary `down`, reducing downtime during normal
 The Kubernetes path accepts a `nodes` list containing any number of control-plane and worker nodes. Each node has a unique name, IP address, and role; exactly one control-plane node is marked `bootstrap = true`. The endpoint, Kubernetes version, storage device, Cilium interface, and load-balancer address pool remain explicit inputs because they are site-specific.
 
 1. Copy `terraform/terraform.tfvars.example` to a local `.tfvars` file and fill in the supported Kubernetes version, stable control-plane endpoint, and `nodes` list.
-2. Run `terraform init`, `terraform fmt`, and `terraform validate` from `terraform/`.
+2. Create a dedicated Gitea service account with read-only access to `whentimeslows/home-services`, then create a read-only personal access token for that account. Do not use an administrator token or commit the token to `terraform.tfvars`.
-3. Boot every KVM VM from the Talos ISO with its install disk attached. Terraform applies the role-specific configuration to every node, installs Talos to `install_disk`, bootstraps the selected control-plane node, and installs Argo CD.
+3. From `terraform/`, export the Gitea credentials for this apply. The Terraform Kubernetes provider will create the Argo CD repository Secret named `gitea-repository` in the `argocd` namespace:
-4. Supply the Gitea credential through Terraform variables or create the Argo CD repository Secret out-of-band. Never commit tokens or private keys.
+
-5. Apply both manifests with `kubectl apply -f bootstrap/applicationsets/`.
+  ```bash
-6. Confirm Argo CD discovers `infrastructure/cilium`, `infrastructure/longhorn`, and `services/vaultwarden`.
+  export TF_VAR_gitea_username="argocd-home-services"
+  export TF_VAR_gitea_password="<read-only-gitea-token>"
+  ```
+
+  The token is stored in Terraform state and in the Kubernetes Secret, so protect the state backend and shell history. Use an environment variable or a protected variable-file mechanism rather than committing the token.
+4. Run `terraform init`, `terraform fmt`, and `terraform validate` from `terraform/`.
+5. Boot every KVM VM from the Talos ISO with its install disk attached. Terraform applies the role-specific configuration to every node, installs Talos to `install_disk`, bootstraps the selected control-plane node, and installs Argo CD.
+6. Export the kubeconfig produced by Terraform before running `kubectl`. Terraform cannot safely infer your shell's active kubeconfig or make a later interactive `kubectl` command part of the apply, but it does expose the generated config as the sensitive `kubeconfig` output:
+
+  ```bash
+  export KUBECONFIG="$HOME/.kube/home-services"
+  mkdir -p "$(dirname "$KUBECONFIG")"
+  terraform output -raw kubeconfig > "$KUBECONFIG"
+  chmod 600 "$KUBECONFIG"
+  kubectl cluster-info
+  ```
+
+  Set `KUBECONFIG` only after `terraform apply` has completed and the `kubeconfig` output exists. This file is a cluster credential and must not be committed or shared.
+7. Apply both ApplicationSets with `kubectl apply -f bootstrap/applicationsets/`.
+8. Confirm Argo CD discovers `infrastructure/cilium`, `infrastructure/longhorn`, and `services/vaultwarden`.
 
 Talos uses its default CNI during bootstrap so Argo CD can start. Cilium is then reconciled as the first infrastructure application. Confirm the LAN interface and address pool before enabling production LoadBalancer services. Longhorn also requires a validated disk or mount on the storage node.