From 06e721841c5087be27bed520cd4b74d91fa1ecf6 Mon Sep 17 00:00:00 2001 From: Erich Blume Date: Mon, 23 Mar 2026 09:51:57 -0700 Subject: [PATCH] Review 12 reference docs: fix stale image refs, expand stubs, add cross-refs Replace hardcoded image tags in Quick Reference tables with pointers to kustomization manifests (tags drift with every container release). Fix Prometheus CNPG scrape target, remove misleading .ts.net URLs, expand external-secrets stub, add backup/disaster-recovery cross-references. Limit doc-reviewer agent to one doc per cycle. Co-Authored-By: Claude Opus 4.6 (1M context) --- .claude/agents/doc-reviewer.md | 11 ++++++----- .../changelog.d/+doc-review-march-2026.doc.md | 1 + docs/reference/kubernetes/external-secrets.md | 19 +++++++++++++++++-- docs/reference/operations/backup.md | 6 ++++-- .../reference/operations/disaster-recovery.md | 4 +++- docs/reference/services/devpi.md | 5 +++-- docs/reference/services/docs.md | 16 ++++++++-------- docs/reference/services/immich.md | 1 + docs/reference/services/jellyfin.md | 1 + docs/reference/services/loki.md | 6 +++--- docs/reference/services/miniflux.md | 6 +++--- docs/reference/services/prometheus.md | 8 ++++---- docs/reference/services/teslamate.md | 8 ++++---- docs/reference/storage/sifaka.md | 1 + 14 files changed, 59 insertions(+), 34 deletions(-) create mode 100644 docs/changelog.d/+doc-review-march-2026.doc.md diff --git a/.claude/agents/doc-reviewer.md b/.claude/agents/doc-reviewer.md index 7e73f8b..5ab941d 100644 --- a/.claude/agents/doc-reviewer.md +++ b/.claude/agents/doc-reviewer.md @@ -11,11 +11,12 @@ You are a documentation reviewer for the BlumeOps homelab infrastructure project ## Workflow 1. Run `mise run docs-review` to see the staleness table and identify the most stale doc -2. Read the identified doc thoroughly -3. Perform the review checklist (below) -4. Check your agent memory for notes from past reviews of this doc or related docs -5. Present your findings as a structured report -6. Update your agent memory with anything you learned +2. **Review exactly ONE document** — the single most stale doc from the table. Do not review multiple docs in one cycle. The main conversation will invoke you again if more reviews are needed. +3. Read the identified doc thoroughly +4. Perform the review checklist (below) +5. Check your agent memory for notes from past reviews of this doc or related docs +6. Present your findings as a structured report +7. Update your agent memory with anything you learned ## Review Checklist diff --git a/docs/changelog.d/+doc-review-march-2026.doc.md b/docs/changelog.d/+doc-review-march-2026.doc.md new file mode 100644 index 0000000..40cbc7f --- /dev/null +++ b/docs/changelog.d/+doc-review-march-2026.doc.md @@ -0,0 +1 @@ +Review and update 12 reference docs: fix stale image references to point at kustomization manifests instead of hardcoded tags, correct Prometheus scrape target, expand external-secrets stub, add cross-references between backup/disaster-recovery docs, and remove misleading `.ts.net` URLs from Quick Reference tables. diff --git a/docs/reference/kubernetes/external-secrets.md b/docs/reference/kubernetes/external-secrets.md index 8efcbaf..3a1e08e 100644 --- a/docs/reference/kubernetes/external-secrets.md +++ b/docs/reference/kubernetes/external-secrets.md @@ -1,6 +1,7 @@ --- title: External Secrets -modified: 2026-02-07 +modified: 2026-03-23 +last-reviewed: 2026-03-23 tags: - kubernetes - secrets @@ -8,4 +9,18 @@ tags: # External Secrets -See [[1password]] in Services. +The [External Secrets Operator](https://external-secrets.io/) syncs secrets from 1Password into Kubernetes Secrets. It runs in the `1password-connect` namespace alongside the 1Password Connect server. + +## How It Works + +Each service that needs secrets defines an `ExternalSecret` resource referencing a 1Password item and field. The operator polls 1Password Connect and creates/updates native Kubernetes Secrets. + +## Manifests + +- **Operator + Connect server:** `argocd/manifests/1password-connect/` +- **Per-service ExternalSecrets:** in each service's manifest directory (e.g., `argocd/manifests/grafana-config/external-secret-*.yaml`) + +## Related + +- [[1password]] - Credential management +- [[security-model]] - Secrets flow architecture diff --git a/docs/reference/operations/backup.md b/docs/reference/operations/backup.md index 5403d13..50d8daa 100644 --- a/docs/reference/operations/backup.md +++ b/docs/reference/operations/backup.md @@ -1,6 +1,7 @@ --- title: Backup -modified: 2026-02-07 +modified: 2026-03-23 +last-reviewed: 2026-03-23 tags: - operations --- @@ -13,4 +14,5 @@ Daily automated backups of BlumeOps data. - [[borgmatic]] - Backup orchestration - [[sifaka|Sifaka]] - Backup target (NAS) -- [[backups|backup-policy]] - What gets backed up and retention +- [[backups]] - What gets backed up and retention +- [[disaster-recovery]] - Recovery procedures diff --git a/docs/reference/operations/disaster-recovery.md b/docs/reference/operations/disaster-recovery.md index 475cf1c..b144aaf 100644 --- a/docs/reference/operations/disaster-recovery.md +++ b/docs/reference/operations/disaster-recovery.md @@ -1,6 +1,7 @@ --- title: Disaster Recovery -modified: 2026-02-10 +modified: 2026-03-23 +last-reviewed: 2026-03-23 tags: - operations --- @@ -18,6 +19,7 @@ Recovery procedures for BlumeOps infrastructure. ## Components +- [[backup]] - Backup overview - [[borgmatic]] - Backup restoration - [[1password]] - Credential recovery (backed up via `mise run op-backup`) - [[forgejo]] - Source of truth for infrastructure code diff --git a/docs/reference/services/devpi.md b/docs/reference/services/devpi.md index 74a05a3..c6493fe 100644 --- a/docs/reference/services/devpi.md +++ b/docs/reference/services/devpi.md @@ -1,6 +1,7 @@ --- title: Devpi -modified: 2026-02-07 +modified: 2026-03-23 +last-reviewed: 2026-03-23 tags: - service - python @@ -18,7 +19,7 @@ PyPI caching proxy and private package index. | **Namespace** | `devpi` | | **ArgoCD App** | `devpi` | | **Storage** | 50Gi PVC | -| **Image** | `registry.ops.eblu.me/blumeops/devpi:latest` | +| **Image** | `registry.ops.eblu.me/blumeops/devpi` (see `argocd/manifests/devpi/kustomization.yaml` for current tag) | ## Indices diff --git a/docs/reference/services/docs.md b/docs/reference/services/docs.md index 6c3bd21..1361d02 100644 --- a/docs/reference/services/docs.md +++ b/docs/reference/services/docs.md @@ -1,6 +1,7 @@ --- title: Docs -modified: 2026-02-08 +modified: 2026-03-23 +last-reviewed: 2026-03-23 tags: - service - documentation @@ -17,7 +18,7 @@ Documentation site built with [Quartz](https://quartz.jzhao.xyz/) and served via | **Public URL** | https://docs.eblu.me | | **Private URL** | `docs.ops.eblu.me` (tailnet only, via [[caddy]]) | | **Namespace** | `docs` | -| **Container** | `registry.ops.eblu.me/blumeops/quartz:v1.0.0` | +| **Image** | `registry.ops.eblu.me/blumeops/quartz` (see `argocd/manifests/docs/kustomization.yaml` for current tag) | | **Source** | `docs/` directory in blumeops repo | | **Build** | Forgejo workflow `build-blumeops.yaml` | | **Public proxy** | [[flyio-proxy]] (Fly.io → Tailscale tunnel) | @@ -31,13 +32,12 @@ Documentation site built with [Quartz](https://quartz.jzhao.xyz/) and served via ## Release Process -Documentation is automatically built and released when changes are pushed to main: +Documentation is built and released via the `build-blumeops` Forgejo workflow (manual dispatch): -1. Workflow detects changes in `docs/` directory -2. Quartz builds static HTML/CSS/JS -3. Assets uploaded as release attachment -4. ArgoCD deployment updated with new `DOCS_RELEASE_URL` -5. Pod restarts and downloads new bundle +1. Quartz builds static HTML/CSS/JS +2. Assets uploaded as Forgejo release attachment +3. Workflow updates `DOCS_RELEASE_URL` in `argocd/manifests/docs/deployment.yaml` and commits to main +4. ArgoCD syncs the updated deployment; new pod downloads the release bundle at startup ## Configuration diff --git a/docs/reference/services/immich.md b/docs/reference/services/immich.md index 915bbed..740dfa4 100644 --- a/docs/reference/services/immich.md +++ b/docs/reference/services/immich.md @@ -1,6 +1,7 @@ --- title: Immich modified: 2026-02-07 +last-reviewed: 2026-03-23 tags: - service - media diff --git a/docs/reference/services/jellyfin.md b/docs/reference/services/jellyfin.md index 85040fc..bbdfafd 100644 --- a/docs/reference/services/jellyfin.md +++ b/docs/reference/services/jellyfin.md @@ -1,6 +1,7 @@ --- title: Jellyfin modified: 2026-02-07 +last-reviewed: 2026-03-23 tags: - service - media diff --git a/docs/reference/services/loki.md b/docs/reference/services/loki.md index cbdc573..2b3b44e 100644 --- a/docs/reference/services/loki.md +++ b/docs/reference/services/loki.md @@ -1,6 +1,7 @@ --- title: Loki -modified: 2026-02-08 +modified: 2026-03-23 +last-reviewed: 2026-03-23 tags: - service - observability @@ -15,9 +16,8 @@ Log aggregation system for BlumeOps infrastructure. | Property | Value | |----------|-------| | **URL** | https://loki.ops.eblu.me | -| **Tailscale URL** | https://loki.tail8d86e.ts.net | | **Namespace** | `monitoring` | -| **Image** | `grafana/loki:3.4.2` | +| **Image** | `registry.ops.eblu.me/blumeops/loki` (see `argocd/manifests/loki/kustomization.yaml` for current tag) | | **Storage** | 50Gi PVC | | **Retention** | 31 days | diff --git a/docs/reference/services/miniflux.md b/docs/reference/services/miniflux.md index 70c1ff2..c34e5f7 100644 --- a/docs/reference/services/miniflux.md +++ b/docs/reference/services/miniflux.md @@ -1,6 +1,7 @@ --- title: Miniflux -modified: 2026-02-07 +modified: 2026-03-23 +last-reviewed: 2026-03-23 tags: - service - rss @@ -15,9 +16,8 @@ Minimalist RSS/Atom feed reader. | Property | Value | |----------|-------| | **URL** | https://feed.ops.eblu.me | -| **Tailscale URL** | https://feed.tail8d86e.ts.net | | **Namespace** | `miniflux` | -| **Image** | `ghcr.io/miniflux/miniflux:latest` | +| **Image** | `registry.ops.eblu.me/blumeops/miniflux` (see `argocd/manifests/miniflux/kustomization.yaml` for current tag) | | **Database** | [[postgresql]] | ## Features diff --git a/docs/reference/services/prometheus.md b/docs/reference/services/prometheus.md index eaf48b1..4d23588 100644 --- a/docs/reference/services/prometheus.md +++ b/docs/reference/services/prometheus.md @@ -1,6 +1,7 @@ --- title: Prometheus -modified: 2026-02-08 +modified: 2026-03-23 +last-reviewed: 2026-03-23 tags: - service - observability @@ -15,9 +16,8 @@ Metrics storage and querying for BlumeOps infrastructure. | Property | Value | |----------|-------| | **URL** | https://prometheus.ops.eblu.me | -| **Tailscale URL** | https://prometheus.tail8d86e.ts.net | | **Namespace** | `monitoring` | -| **Image** | `prom/prometheus:v3.2.1` | +| **Image** | `registry.ops.eblu.me/blumeops/prometheus` (see `argocd/manifests/prometheus/kustomization.yaml` for current tag) | | **Storage** | 50Gi PVC | | **Manifests** | `argocd/manifests/prometheus/` | @@ -33,7 +33,7 @@ Metrics storage and querying for BlumeOps infrastructure. | Target | Metrics | |--------|---------| | `sifaka:9100` | [[sifaka|Sifaka]] NAS (node_exporter) | -| `cnpg-metrics.tail8d86e.ts.net:9187` | [[postgresql|CloudNativePG]] metrics | +| `blumeops-pg-metrics-tailscale.databases.svc.cluster.local:9187` | [[postgresql|CloudNativePG]] metrics | | `kube-state-metrics.monitoring.svc:8080` | Kubernetes resource metrics | ## Related diff --git a/docs/reference/services/teslamate.md b/docs/reference/services/teslamate.md index a891255..f02e979 100644 --- a/docs/reference/services/teslamate.md +++ b/docs/reference/services/teslamate.md @@ -1,6 +1,7 @@ --- title: TeslaMate -modified: 2026-02-07 +modified: 2026-03-23 +last-reviewed: 2026-03-23 tags: - service - vehicle @@ -8,16 +9,15 @@ tags: # TeslaMate -Self-hosted Tesla data logger collecting vehicle telemetry from the Tesla Owner API. +Self-hosted Tesla data logger collecting vehicle telemetry from the Tesla API. ## Quick Reference | Property | Value | |----------|-------| | **URL** | https://tesla.ops.eblu.me | -| **Tailscale URL** | https://tesla.tail8d86e.ts.net | | **Namespace** | `teslamate` | -| **Image** | `teslamate/teslamate:2.2.0` | +| **Image** | `registry.ops.eblu.me/blumeops/teslamate` (see `argocd/manifests/teslamate/kustomization.yaml` for current tag) | | **Database** | [[postgresql]] | ## Data Collected diff --git a/docs/reference/storage/sifaka.md b/docs/reference/storage/sifaka.md index a994923..31fe90a 100644 --- a/docs/reference/storage/sifaka.md +++ b/docs/reference/storage/sifaka.md @@ -1,6 +1,7 @@ --- title: Sifaka modified: 2026-02-09 +last-reviewed: 2026-03-23 tags: - storage ---