feat: initial homelab-gitops declarative structure (Terraform & ArgoCD)

README.md

@@ -1,3 +1,40 @@
-# homelab-gitops
+# Snarfnet Homelab GitOps & Infrastructure as Code
 
-Snarfnet Homelab GitOps, Terraform, and ArgoCD Declarations
+This repository contains declarative configurations for the Snarfnet homelab infrastructure across Kubernetes clusters (`spaceport`, `aerodrome`), Docker Swarm (`shipyard`), Synology NAS storage arrays, and Harvester HCI.
+
+## Repository Layout
+
+```text
+homelab-gitops/
+├── terraform/
+│   ├── authentik/       # Authentik Providers, Applications, Proxy ForwardAuth, and Security Policies
+│   ├── harvester/       # Declarative VLAN networks, VM templates, and SSH keys
+│   ├── shipyard-swarm/  # Docker Swarm stacks (NPM, Gotify, Homebox, Peanut)
+│   └── synology/        # Synology shared folders (kubernetes, docker, backups, media) and NFS rules
+├── argocd/
+│   ├── bootstrap/       # Root App-of-Apps and Project definitions
+│   ├── spaceport/       # Applications hosted on spaceport (Gitea, Zabbix, Jenkins, Semaphore, Coder, Homepage)
+│   └── aerodrome/       # Applications hosted on aerodrome (Authentik, AWX, Grafana, Uptime Kuma, Longhorn)
+└── manifests/           # Raw Kubernetes YAML manifests managed by ArgoCD
+    ├── spaceport/
+    └── aerodrome/
+```
+
+## Terraform State Storage
+
+Terraform state is stored in Gitea's built-in HTTP State Backend:
+- Backend URL: `https://git.snarfnet.net/api/packages/snarf/terraform/state/<module>`
+- HTTP Authentication: Basic auth via Gitea account (`snarf`)
+
+## ArgoCD GitOps Engine
+
+- **ArgoCD Server:** `https://argo.snarfnet.net` (hosted on `spaceport` in namespace `infrastructure`)
+- **Target Clusters:**
+  - In-cluster (`https://kubernetes.default.svc`): Spaceport (`sninfr0lnxctl01–04`, `sninfr0lnxwrk01–06`)
+  - Remote cluster (`https://140.44.4.11:6443`): Aerodrome (`sninfr2lnxctl01–03`, `sninfr2lnxwrk01–07`)
+- **Sync Policy:**
+  - `automated: { prune: false, selfHeal: true }`
+  - `syncOptions: [ServerSideApply=true, CreateNamespace=true]`
+- **Notifications Pipeline:**
+  - Webhook integration to Gotify (`http://140.44.4.70:8090/message?token=A8aWxGiToPsAuToMaTiO`)
+  - Automated failover bridge to Discord channel `#infra-alerts`