add argocd documentation

kubernetes/apps/README.md

@@ -0,0 +1,43 @@
+# Kubernetes Apps
+
+This folder holds the actual Kubernetes workload manifests for every app managed via Argo CD's GitOps flow. Each subfolder is one application, named after the app itself:
+
+```
+kubernetes/apps/
+├── README.md              ← you are here
+├── homepage/
+│   ├── deployment.yaml
+│   ├── service.yaml
+│   ├── configmap.yaml
+│   ├── ingress.yaml
+│   └── kustomization.yaml
+├── <name>/                 ← new apps go here
+│   ├── ...
+│   └── kustomization.yaml
+```
+
+## What lives here
+
+- **Workload manifests** — `Deployment`, `Service`, `ConfigMap`, `Ingress`, `Secret`, etc. These describe the pods, networking, and config that Argo CD applies to the cluster.
+- **`kustomization.yaml`** — the Kustomize entry point for the app. Argo CD watches the path this file declares, so every app folder must include one and list every sibling manifest under `resources:`.
+
+These are the files that end up running in the cluster. This is "what runs."
+
+## What does *not* live here
+
+- **Argo CD `Application` objects.** Those live in the sibling [`../argocd-apps/`](../argocd-apps/README.md) folder, deliberately kept separate so Argo CD never watches its own definitions.
+- **Namespace-scoped governance objects.** The cluster-level `LimitRange` and `ResourceQuota` live in [`../resource-limits/`](../resource-limits/resource-limits.yaml), applied once at cluster setup rather than per-app.
+
+## Relationship to the rest of the repo
+
+Every always-on Docker Compose service in this repo (see [`docker-compose/`](../../docker-compose/)) has a self-contained folder with its own `docker-compose.yml`. The Kubernetes side mirrors that convention — one folder per app, fully self-contained — so the structure on both sides is parallel and easy to navigate.
+
+## Adding a new app
+
+See [ArgoCD](docs/argocd.md#adding-a-new-app) for the full walkthrough. In short:
+
+1. Create `kubernetes/apps/<name>/` with manifests + `kustomization.yaml`.
+2. Create the matching `kubernetes/argocd-apps/<name>/<name>-app.yaml` Application manifest pointing at that path.
+3. `kubectl apply` the Application once — future changes flow through git.
+
+[← Back to Home](../../docs/Home.md)

kubernetes/argocd-apps/README.md

@@ -0,0 +1,69 @@
+# Argo CD Application Manifests
+
+This folder holds the **Argo CD `Application` objects** — the manifests that tell Argo CD which Git path to watch and which cluster/namespace to deploy into. Each subfolder corresponds to one app, matching the name used under [`../apps/`](../apps/README.md):
+
+```
+kubernetes/argocd-apps/
+├── README.md              ← you are here
+├── homepage/
+│   └── homepage-app.yaml
+└── <name>/
+    └── <name>-app.yaml
+```
+
+## What lives here
+
+- **One `Application` YAML per app**, named `<name>-app.yaml`. This is the Argo CD control plane entry point — it sets the source repo, target revision, git `path`, destination server and namespace, and sync policy (automated with `prune` and `selfHeal`).
+
+Example (from `homepage/homepage-app.yaml`):
+
+```yaml
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: homepage
+  namespace: argocd
+spec:
+  project: default
+  source:
+    repoURL: https://github.com/rezayaghobi-dev/homelab
+    targetRevision: main
+    path: kubernetes/apps/homepage
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: homepage
+  syncPolicy:
+    automated:
+      prune: true
+      selfHeal: true
+    syncOptions:
+      - CreateNamespace=true
+```
+
+## What does *not* live here
+
+- **Workload manifests** (`Deployment`, `Service`, `Ingress`, etc.). Those live in the sibling [`../apps/`](../apps/README.md) folder. This separation is deliberate: Argo CD should never watch its own `Application` definitions, otherwise a recursive sync loop becomes possible.
+
+## Why this separation matters
+
+Keeping "what tells Argo CD to run" (`<name>-app.yaml`) and "what actually runs" (the manifests in `../apps/<name>/`) in different folders means:
+
+- **No accidental self-watch.** Argo CD watches `kubernetes/apps/`, not `kubernetes/argocd-apps/`. An Application manifest changing its own `path` would have no effect — it'd be out of the watched tree entirely.
+- **Independent lifecycle.** The Application object is applied once via `kubectl`; everything after that — the Deployments, Services, Ingresses it ultimately creates — flows from git through Argo CD's reconciliation loop.
+- **One job per file.** Adding an app means adding one file here (the Application) and one directory there (the manifests). Easy to audit, easy to delete.
+
+## Applying a new Application
+
+After creating `kubernetes/argocd-apps/<name>/<name>-app.yaml`, apply it once:
+
+```bash
+kubectl apply -f kubernetes/argocd-apps/<name>/<name>-app.yaml
+```
+
+Argo CD picks it up immediately, creates the app in its UI, and begins syncing. After this single `kubectl` call, **all** future changes flow through git — modifying the Application manifest itself is rarely needed once it's running.
+
+## Relationship to the rest of the repo
+
+The folder structure mirrors [`../apps/`](../apps/README.md) one-to-one: each app under `kubernetes/argocd-apps/` has a matching folder under `kubernetes/apps/`. This isn't strictly enforced by Argo CD, but keeping the two trees parallel makes it trivial to trace "which Application watches which manifests."
+
+[← Back to Home](../../docs/Home.md)