From 6c77b8e7f8e7558b7edd06c063a4a5939c6c2125 Mon Sep 17 00:00:00 2001
From: Brad Stein <Brad.Stein@gmail.com>
Date: Fri, 12 Dec 2025 00:50:02 -0300
Subject: [PATCH] restore docs after gitignore change

---
 clusters/oceanus/README.md    |  5 +++++
 hosts/styx/README.md          |  2 ++
 services/keycloak/README.md   | 27 +++++++++++++++++++++++++++
 services/monitoring/README.md | 28 ++++++++++++++++++++++++++++
 4 files changed, 62 insertions(+)
 create mode 100644 clusters/oceanus/README.md
 create mode 100644 hosts/styx/README.md
 create mode 100644 services/keycloak/README.md
 create mode 100644 services/monitoring/README.md

diff --git a/clusters/oceanus/README.md b/clusters/oceanus/README.md
new file mode 100644
index 0000000..d91b52f
--- /dev/null
+++ b/clusters/oceanus/README.md
@@ -0,0 +1,5 @@
+# Oceanus Cluster Scaffold
+
+This directory prepares the Flux and Kustomize layout for a future Oceanus-managed cluster.
+Populate `flux-system/` with `gotk-components.yaml` and related manifests after running `flux bootstrap`.
+Define node-specific resources under `infrastructure/modules/profiles/oceanus-validator/` and reference workloads in `applications/` as they come online.
diff --git a/hosts/styx/README.md b/hosts/styx/README.md
new file mode 100644
index 0000000..992bac5
--- /dev/null
+++ b/hosts/styx/README.md
@@ -0,0 +1,2 @@
+# hosts/styx/README.md
+Styx is air-gapped; provisioning scripts live under `scripts/`.
diff --git a/services/keycloak/README.md b/services/keycloak/README.md
new file mode 100644
index 0000000..bf7c21b
--- /dev/null
+++ b/services/keycloak/README.md
@@ -0,0 +1,27 @@
+# services/keycloak
+
+Keycloak is deployed via raw manifests and backed by the shared Postgres (`postgres-service.postgres.svc.cluster.local:5432`). Create these secrets before applying:
+
+```bash
+# DB creds (per-service DB/user in shared Postgres)
+kubectl -n sso create secret generic keycloak-db \
+  --from-literal=username=keycloak \
+  --from-literal=password='<DB_PASSWORD>' \
+  --from-literal=database=keycloak
+
+# Admin console creds (maps to KC admin user)
+kubectl -n sso create secret generic keycloak-admin \
+  --from-literal=username=brad@bstein.dev \
+  --from-literal=password='<ADMIN_PASSWORD>'
+```
+
+Apply:
+
+```bash
+kubectl apply -k services/keycloak
+```
+
+Notes
+- Service: `keycloak.sso.svc:80` (Ingress `sso.bstein.dev`, TLS via cert-manager).
+- Uses Postgres schema `public`; DB/user should be provisioned in the shared Postgres instance.
+- Health endpoints on :9000 are wired for probes.
diff --git a/services/monitoring/README.md b/services/monitoring/README.md
new file mode 100644
index 0000000..835ae1d
--- /dev/null
+++ b/services/monitoring/README.md
@@ -0,0 +1,28 @@
+# services/monitoring
+
+## Grafana admin secret
+
+The Grafana Helm release expects a pre-existing secret named `grafana-admin`
+in the `monitoring` namespace. Create or rotate it with:
+
+```bash
+kubectl create secret generic grafana-admin \
+  --namespace monitoring \
+  --from-literal=admin-user=admin \
+  --from-literal=admin-password='REPLACE_ME'
+```
+
+Update the password whenever you rotate credentials.
+
+## DCGM exporter image
+
+The NVIDIA GPU metrics DaemonSet expects `registry.bstein.dev/monitoring/dcgm-exporter:4.4.2-4.7.0-ubuntu22.04`, mirrored from `docker.io/nvidia/dcgm-exporter:4.4.2-4.7.0-ubuntu22.04`. Refresh it in Zot when bumping versions:
+
+```bash
+skopeo copy \
+  --all \
+  docker://docker.io/nvidia/dcgm-exporter:4.4.2-4.7.0-ubuntu22.04 \
+  docker://registry.bstein.dev/monitoring/dcgm-exporter:4.4.2-4.7.0-ubuntu22.04
+```
+
+When finished mirroring from the control-plane, you can remove temporary tooling with `sudo apt-get purge -y skopeo && sudo apt-get autoremove -y` and clear `~/.config/containers/auth.json`.