eblume/blumeops
1
1
Fork 0
Code Issues Pull requests Projects Releases 83 Packages Wiki Activity Actions
blumeops/docs/reference/reference.md

95 lines
3.1 KiB
Markdown
Raw Normal View History

Phase 2: Add Reference section with 24 technical reference cards (#88) ## Summary - Create `docs/reference/` section with 24 technical reference cards - Services (16): alloy, argocd, borgmatic, 1password, forgejo, grafana, jellyfin, kiwix, loki, miniflux, navidrome, postgresql, prometheus, teslamate, transmission, zot - Infrastructure (3): hosts, tailscale, routing - Kubernetes (2): cluster, apps - Storage (2): sifaka, backups - Update README to mark Phase 2 as complete - Add towncrier changelog fragment ## Deployment and Testing - [ ] Build docs locally to verify wiki-links resolve - [ ] Deploy via ArgoCD and verify at docs.ops.eblu.me/reference/ 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/88
2026-02-03 14:27:37 -08:00
---
Update all docs titles to human-readable (#117) ## Summary - Updated frontmatter `title:` in all 63 doc cards from slug-case to human-readable (e.g. `borgmatic` → `Borgmatic`, `ai-assistance-guide` → `AI Assistance Guide`) - Titles now closely match file stems so `[[wiki-links]]` render naturally without alternate anchor text - Corrected titles that diverged from stems (e.g. `host-inventory` → `Hosts`, `grafana-alloy` → `Alloy`, `argocd-applications` → `Apps`) - Deleted `title-test-alpha.md` and `title-test-beta.md` test cards and removed their reference index entry ## Deployment and Testing - [x] `docs-check-links` passes — all wiki-links valid - [x] `docs-check-index` passes - [x] `docs-check-filenames` passes - [ ] Verify titles render correctly on docs site after deploy Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/117
2026-02-07 21:44:57 -08:00
title: Reference
Add Ollama reference card and update indexes Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-04 19:43:14 -08:00
modified: 2026-03-04
Phase 2: Add Reference section with 24 technical reference cards (#88) ## Summary - Create `docs/reference/` section with 24 technical reference cards - Services (16): alloy, argocd, borgmatic, 1password, forgejo, grafana, jellyfin, kiwix, loki, miniflux, navidrome, postgresql, prometheus, teslamate, transmission, zot - Infrastructure (3): hosts, tailscale, routing - Kubernetes (2): cluster, apps - Storage (2): sifaka, backups - Update README to mark Phase 2 as complete - Add towncrier changelog fragment ## Deployment and Testing - [ ] Build docs locally to verify wiki-links resolve - [ ] Deploy via ArgoCD and verify at docs.ops.eblu.me/reference/ 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/88
2026-02-03 14:27:37 -08:00
tags:
- reference
---
# Reference
Technical specifications, inventories, and configuration details for BlumeOps infrastructure.
## Services
Individual service reference cards with URLs and configuration details.
| Service | Description | Location |
|---------|-------------|----------|
Enforce unique doc filenames and simple wiki-links (#109) ## Summary - Rename section index files to match their titles (tutorials.md, reference.md, how-to.md, explanation.md) so all filenames are unique - Convert all ~47 path-based wiki-links to simple filename format across 15 files - Update doc-filenames task to no longer skip index.md files - Update doc-links task to reject path-based links containing '/' This ensures all wiki-links work correctly in obsidian.nvim by making links resolvable by filename alone. ## Testing - `mise run doc-filenames` - all unique - `mise run doc-links` - no broken or path-based links - `mise run doc-titles` - no duplicates Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/109
2026-02-04 17:21:34 -08:00
| [[alloy|Alloy]] | Observability collector (metrics & logs) | indri + k8s |
Convert wiki-link titles to lowercase slugs (#92) ## Summary - Convert all frontmatter titles to lowercase-hyphenated format (e.g., `grafana-alloy` instead of `Grafana Alloy`) - Update all wiki-links to use the new slug format - Update `doc-titles` task to validate slug format (lowercase, hyphens only) Quartz appears to require titles without spaces for wiki-link resolution. ## Deployment and Testing - [x] Pre-commit hooks pass (`doc-titles` and `doc-links`) - [ ] Build docs v1.0.8 and deploy - [ ] Verify wiki-links resolve correctly (e.g., `[[grafana-alloy]]`) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/92
2026-02-03 16:06:35 -08:00
| [[argocd]] | GitOps continuous delivery | k8s |
| [[borgmatic]] | Backup system | indri |
Add doc-random task and documentation improvements (#98) ## Summary - Add `doc-random` mise task that selects a random documentation card for review - Add how-to/knowledgebase section with review-documentation guide - Add Caddy reference card with proxy configuration details - Fix replication tutorial sequence (tailscale-setup now links to core-services) - Fix "BluemeOps" typo in tailscale-setup - Clean up obsolete zk/ directory references from doc-links ## Deployment and Testing - [x] `mise run doc-random` works and displays a random card - [x] `mise run doc-links` passes (all wiki-links valid) - [x] Pre-commit hooks pass 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/98
2026-02-03 21:17:58 -08:00
| [[caddy]] | Reverse proxy & TLS termination | indri |
Convert wiki-link titles to lowercase slugs (#92) ## Summary - Convert all frontmatter titles to lowercase-hyphenated format (e.g., `grafana-alloy` instead of `Grafana Alloy`) - Update all wiki-links to use the new slug format - Update `doc-titles` task to validate slug format (lowercase, hyphens only) Quartz appears to require titles without spaces for wiki-link resolution. ## Deployment and Testing - [x] Pre-commit hooks pass (`doc-titles` and `doc-links`) - [ ] Build docs v1.0.8 and deploy - [ ] Verify wiki-links resolve correctly (e.g., `[[grafana-alloy]]`) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/92
2026-02-03 16:06:35 -08:00
| [[1password]] | Secrets management | cloud + k8s |
| [[forgejo]] | Git forge & CI/CD | indri |
Fix services-check and update docs for Frigate migration to ringtail (#218) ## Summary - Move mosquitto, ntfy, frigate, frigate-notify pod checks from `minikube-indri` to `k3s-ringtail` context in `services-check` - Add `nvidia-device-plugin` pod check for ringtail k3s - Rename "Kubernetes pods" section to "Indri minikube pods" for clarity - Update 8 documentation files to reflect the migration completed in PRs #216/#217 ## Files Changed | File | Change | |------|--------| | `mise-tasks/services-check` | Move 4 pod checks to k3s-ringtail, add nvidia-device-plugin | | `docs/reference/services/frigate.md` | Image→tensorrt, detector→ONNX/CUDA, shm→512Mi | | `docs/reference/infrastructure/ringtail.md` | List actual k3s workloads | | `docs/reference/infrastructure/indri.md` | Note frigate migration | | `docs/explanation/architecture.md` | Add ringtail to diagram + compute layer | | `docs/reference/kubernetes/cluster.md` | Note two clusters, add k3s section | | `docs/reference/reference.md` | Update frigate/ntfy location | | `docs/how-to/plans/completed/operationalize-reolink-camera.md` | Add post-completion migration note | | `CLAUDE.md` | Add k3s-ringtail context guidance | ## Test plan - [ ] `mise run services-check` — all checks pass - [ ] Review each doc for accuracy against deployed state 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/218
2026-02-19 14:38:21 -08:00
| [[frigate]] | Network video recorder | k8s (ringtail) |
Convert wiki-link titles to lowercase slugs (#92) ## Summary - Convert all frontmatter titles to lowercase-hyphenated format (e.g., `grafana-alloy` instead of `Grafana Alloy`) - Update all wiki-links to use the new slug format - Update `doc-titles` task to validate slug format (lowercase, hyphens only) Quartz appears to require titles without spaces for wiki-link resolution. ## Deployment and Testing - [x] Pre-commit hooks pass (`doc-titles` and `doc-links`) - [ ] Build docs v1.0.8 and deploy - [ ] Verify wiki-links resolve correctly (e.g., `[[grafana-alloy]]`) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/92
2026-02-03 16:06:35 -08:00
| [[grafana]] | Dashboards & visualization | k8s |
| [[immich]] | Photo management | k8s |
| [[jellyfin]] | Media server | indri |
Add JobSync reference card, observability docs, and RAPIDAPI_KEY plumbing (#289) ## Summary - Add JobSync service reference card (`docs/reference/services/jobsync.md`) with architecture, secrets, observability, and JSearch API docs - Add JobSync and Ollama to ringtail's workloads table (both were missing) - Add JobSync to the reference index - Wire `RAPIDAPI_KEY` through ExternalSecret and deployment env var for JSearch job search automation - Document Loki log queries for observability (no metrics endpoint exists) - Update deploy-jobsync how-to with new env var, observability section, and reference card link ## Deployment and Testing - [ ] Sign up for RapidAPI JSearch API (free tier: 500 req/month) - [ ] Add `rapidapi_key` field to "JobSync" 1Password item - [ ] Merge PR - [ ] `argocd app sync jobsync` to pick up new env var - [ ] Verify job search works at https://jobsync.ops.eblu.me/dashboard/automations Reviewed-on: https://forge.eblu.me/eblume/blumeops/pulls/289
2026-03-08 15:06:52 -07:00
| [[jobsync]] | Job application tracker | k8s (ringtail) |
Convert wiki-link titles to lowercase slugs (#92) ## Summary - Convert all frontmatter titles to lowercase-hyphenated format (e.g., `grafana-alloy` instead of `Grafana Alloy`) - Update all wiki-links to use the new slug format - Update `doc-titles` task to validate slug format (lowercase, hyphens only) Quartz appears to require titles without spaces for wiki-link resolution. ## Deployment and Testing - [x] Pre-commit hooks pass (`doc-titles` and `doc-links`) - [ ] Build docs v1.0.8 and deploy - [ ] Verify wiki-links resolve correctly (e.g., `[[grafana-alloy]]`) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/92
2026-02-03 16:06:35 -08:00
| [[kiwix]] | Offline Wikipedia & ZIM archives | k8s |
| [[loki]] | Log aggregation | k8s |
Add OpenTelemetry distributed tracing (Tempo + Beyla eBPF) (#286) ## Summary Adds the third observability pillar — **distributed tracing** — alongside existing metrics (Prometheus) and logs (Loki). - **Grafana Tempo 2.10.1** on minikube-indri for trace storage with 7d retention, OTLP receivers, and `metrics_generator` that remote-writes span-metrics (RED) to Prometheus - **Beyla eBPF auto-instrumentation** via a privileged Alloy DaemonSet on ringtail — instruments HTTP services (Frigate, ntfy, Ollama, Immich) without code changes - **Grafana integration** — Tempo datasource with trace↔log and trace↔metrics correlation, plus Loki derivedFields for trace ID linking - **Prometheus** scrapes Tempo operational metrics ### Architecture ``` ringtail (k3s) indri (minikube) ┌──────────────────────┐ ┌─────────────────────┐ │ Alloy+Beyla (eBPF) │──OTLP HTTP────────→ │ Tempo │ │ ↳ Frigate, ntfy, │ via tailnet │ ↳ trace storage │ │ Ollama, Immich │ │ ↳ RED → Prometheus │ └──────────────────────┘ │ │ │ Grafana │ │ ↳ Tempo datasource │ └─────────────────────┘ ``` ### New files (12) - `docs/reference/services/tempo.md` — reference doc - `docs/changelog.d/feature-otel-tracing.feature.md` - `argocd/apps/tempo.yaml` + `argocd/manifests/tempo/` (6 files) - `argocd/apps/alloy-tracing-ringtail.yaml` + `argocd/manifests/alloy-tracing-ringtail/` (4 files) ### Modified files (6) - `argocd/manifests/grafana/datasources.yaml` — Tempo datasource + Loki derivedFields - `argocd/manifests/prometheus/prometheus.yml` — Tempo scrape target - `service-versions.yaml` — tempo + alloy-tracing-ringtail entries - `docs/reference/services/grafana.md` — Tempo in datasources table - `docs/reference/reference.md` — Tempo in services index - `docs/reference/operations/observability.md` — Tempo in components list ## Deployment and Testing - [ ] Sync `apps` app to pick up new Application definitions - [ ] `argocd app set tempo --revision feature/otel-tracing && argocd app sync tempo` - [ ] Verify Tempo pod: `kubectl --context=minikube-indri get pods -n monitoring -l app=tempo` - [ ] Verify Tempo ready: port-forward 3200 and `curl localhost:3200/ready` - [ ] Verify Tailscale ingresses: `kubectl --context=minikube-indri get ingress -n monitoring` - [ ] `argocd app set alloy-tracing-ringtail --revision feature/otel-tracing && argocd app sync alloy-tracing-ringtail` - [ ] Check Beyla discovery in alloy-tracing logs on ringtail - [ ] Sync grafana-config for updated datasources - [ ] Sync prometheus for updated scrape config - [ ] Test Grafana Tempo datasource connection - [ ] Generate test traffic and search traces in Grafana Explore → Tempo - [ ] After merge: reset all ArgoCD app revisions back to main Reviewed-on: https://forge.eblu.me/eblume/blumeops/pulls/286
2026-03-05 10:51:07 -08:00
| [[tempo]] | Distributed tracing | k8s |
Convert wiki-link titles to lowercase slugs (#92) ## Summary - Convert all frontmatter titles to lowercase-hyphenated format (e.g., `grafana-alloy` instead of `Grafana Alloy`) - Update all wiki-links to use the new slug format - Update `doc-titles` task to validate slug format (lowercase, hyphens only) Quartz appears to require titles without spaces for wiki-link resolution. ## Deployment and Testing - [x] Pre-commit hooks pass (`doc-titles` and `doc-links`) - [ ] Build docs v1.0.8 and deploy - [ ] Verify wiki-links resolve correctly (e.g., `[[grafana-alloy]]`) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/92
2026-02-03 16:06:35 -08:00
| [[miniflux]] | RSS feed reader | k8s |
| [[navidrome]] | Music streaming | k8s |
Fix services-check and update docs for Frigate migration to ringtail (#218) ## Summary - Move mosquitto, ntfy, frigate, frigate-notify pod checks from `minikube-indri` to `k3s-ringtail` context in `services-check` - Add `nvidia-device-plugin` pod check for ringtail k3s - Rename "Kubernetes pods" section to "Indri minikube pods" for clarity - Update 8 documentation files to reflect the migration completed in PRs #216/#217 ## Files Changed | File | Change | |------|--------| | `mise-tasks/services-check` | Move 4 pod checks to k3s-ringtail, add nvidia-device-plugin | | `docs/reference/services/frigate.md` | Image→tensorrt, detector→ONNX/CUDA, shm→512Mi | | `docs/reference/infrastructure/ringtail.md` | List actual k3s workloads | | `docs/reference/infrastructure/indri.md` | Note frigate migration | | `docs/explanation/architecture.md` | Add ringtail to diagram + compute layer | | `docs/reference/kubernetes/cluster.md` | Note two clusters, add k3s section | | `docs/reference/reference.md` | Update frigate/ntfy location | | `docs/how-to/plans/completed/operationalize-reolink-camera.md` | Add post-completion migration note | | `CLAUDE.md` | Add k3s-ringtail context guidance | ## Test plan - [ ] `mise run services-check` — all checks pass - [ ] Review each doc for accuracy against deployed state 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/218
2026-02-19 14:38:21 -08:00
| [[ntfy]] | Push notifications | k8s (ringtail) |
Convert wiki-link titles to lowercase slugs (#92) ## Summary - Convert all frontmatter titles to lowercase-hyphenated format (e.g., `grafana-alloy` instead of `Grafana Alloy`) - Update all wiki-links to use the new slug format - Update `doc-titles` task to validate slug format (lowercase, hyphens only) Quartz appears to require titles without spaces for wiki-link resolution. ## Deployment and Testing - [x] Pre-commit hooks pass (`doc-titles` and `doc-links`) - [ ] Build docs v1.0.8 and deploy - [ ] Verify wiki-links resolve correctly (e.g., `[[grafana-alloy]]`) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/92
2026-02-03 16:06:35 -08:00
| [[postgresql]] | Database cluster | k8s |
| [[prometheus]] | Metrics collection | k8s |
| [[teslamate]] | Tesla data logger | k8s |
| [[transmission]] | BitTorrent daemon | k8s |
| [[zot]] | Container registry | indri |
Complete Phase 6: documentation cleanup and integration (#97) ## Summary - Delete `docs/zk/` directory - all useful content migrated to structured docs - Delete `docs/README.md` - `docs/index.md` is now the documentation root - Add `devpi` reference card and `use-pypi-proxy` how-to guide - Add maintenance notes to `indri` reference (sleep prevention, passwordless sudo) - Add iCloud Photos backup note to `borgmatic` reference - Rewrite `zk-docs` mise task to prime AI context with key docs instead of legacy cards - Update `CLAUDE.md` and `README.md` to remove zk references - Update `exploring-the-docs` with AI context priming section This completes the Diataxis documentation restructuring. All six phases are now done. ## Deployment and Testing - [x] Pre-commit hooks pass (including doc-links validator) - [ ] Build and deploy to docs.ops.eblu.me to verify rendering 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/97
2026-02-03 20:52:37 -08:00
| [[devpi]] | PyPI caching proxy | k8s |
Add CV service reference card and docs updates (#171) ## Summary - Add CV service reference card (`docs/reference/services/cv.md`) - Add CV to services index, ArgoCD apps registry, and Caddy proxied services table - Changelog fragment ## Files changed - `docs/reference/services/cv.md` (new) — CV reference card - `docs/reference/reference.md` — Add CV to services table - `docs/reference/kubernetes/apps.md` — Add CV to app registry - `docs/reference/services/caddy.md` — Add CV to proxied k8s services - `docs/changelog.d/cv-docs.doc.md` (new) — Changelog fragment Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/171
2026-02-12 11:45:32 -08:00
| [[cv]] | Resume / CV site | k8s |
Deploy Authentik identity provider (C2 Mikado) (#227) ## Summary C2 Mikado chain for deploying Authentik as the SSO identity provider, replacing Dex. This PR will evolve over multiple sessions. Each iteration adds documentation (prerequisite cards) and eventually code as leaf nodes are resolved. ## Current Mikado State - **Goal:** `deploy-authentik` (active) - **Leaf prerequisites:** - `build-authentik-container` — Build Nix container image - `provision-authentik-database` — Create PostgreSQL database on CNPG cluster - `create-authentik-secrets` — Create 1Password item with credentials ## Process refinements - Updated agent-change-process with lessons from first attempt: reset code before committing cards, open PRs early ## Test plan - [ ] `mise run docs-mikado` shows correct dependency chain - [ ] Leaf nodes can be worked independently - [ ] Container builds on ringtail - [ ] Authentik starts and reaches healthy state - [ ] Forgejo OAuth2 connector works Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/227
2026-02-20 12:55:59 -08:00
| [[authentik]] | OIDC identity provider | k8s (ringtail) |
Add Phase 3 tutorials with audience targeting (#94) ## Summary - Create tutorials directory structure with index page - Add 5 main tutorials targeting different audiences: - **what-is-blumeops** (Reader, AI) - High-level orientation - **exploring-the-docs** (All) - Navigation guide - **ai-assistance-guide** (AI, Owner) - Context for AI-assisted operations - **contributing** (Contributor) - First contribution workflow - **replicating-blumeops** (Replicator) - Overview for building similar setup - Add 4 replication sub-tutorials: - tailscale-setup, kubernetes-bootstrap, argocd-config, observability-stack - Update README.md to mark Phase 3 complete - Add changelog fragment Each tutorial explicitly identifies its target audiences and links to reference material rather than re-explaining concepts. ## Deployment and Testing - [x] All pre-commit hooks pass (doc-links validates wiki links) - [ ] Build docs via workflow to verify rendering - [ ] Review content for accuracy 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/94
2026-02-03 18:51:57 -08:00
| [[docs]] | Documentation site (Quartz) | k8s |
Add Fly.io public reverse proxy for docs.eblu.me (#120) ## Summary - Adds a Fly.io reverse proxy (`blumeops-proxy`) that tunnels public traffic to homelab services over Tailscale - First service exposed: `docs.eblu.me` — the Quartz static docs site - Includes Pulumi IaC for Tailscale auth key/ACLs and Gandi DNS CNAME - Adds mise tasks (`fly-deploy`, `fly-setup`, `fly-shutoff`) and Forgejo CI workflow ## Key details - Fly.io Firecracker VMs support TUN devices natively — no userspace networking needed - Tailscale auth key is `preauthorized=True` to avoid device approval hangs on container restarts - nginx caches aggressively for the static site; health check is on the default_server block - ACLs restrict `tag:flyio-proxy` to `tag:k8s` on port 443 only - DNS CNAME deployed and verified: `docs.eblu.me` → `blumeops-proxy.fly.dev` ## Test plan - [x] `curl -sf https://blumeops-proxy.fly.dev/healthz` returns `ok` - [x] `curl -I -H "Host: docs.eblu.me" https://blumeops-proxy.fly.dev/` returns 200 with `X-Cache-Status` - [x] `curl -I https://docs.eblu.me/` returns 200 with valid Let's Encrypt cert - [x] `dig forge.ops.eblu.me` still resolves to 100.98.163.89 (private services unaffected) - [x] Set `FLY_DEPLOY_TOKEN` Forgejo Actions secret for CI auto-deploy 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/120
2026-02-08 02:36:19 -08:00
| [[flyio-proxy]] | Public reverse proxy (Fly.io + Tailscale) | Fly.io |
Add Ollama reference card and update indexes Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-04 19:43:14 -08:00
| [[ollama]] | LLM inference server | k8s (ringtail) |
Add how-to guide for restarting indri (#108) ## Summary - Add `docs/how-to/restart-indri.md` with safe shutdown and startup procedures - Add `docs/reference/services/automounter.md` documenting the SMB share automounter app - Update indri reference card with GUI applications section - Update how-to and reference indexes ## Test plan - [ ] Review restart-indri.md for accuracy - [ ] Verify AutoMounter details are correct - [ ] Perform the actual restart using this guide 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/108
2026-02-04 14:39:48 -08:00
| [[automounter]] | SMB share automounter | indri |
Phase 2: Add Reference section with 24 technical reference cards (#88) ## Summary - Create `docs/reference/` section with 24 technical reference cards - Services (16): alloy, argocd, borgmatic, 1password, forgejo, grafana, jellyfin, kiwix, loki, miniflux, navidrome, postgresql, prometheus, teslamate, transmission, zot - Infrastructure (3): hosts, tailscale, routing - Kubernetes (2): cluster, apps - Storage (2): sifaka, backups - Update README to mark Phase 2 as complete - Add towncrier changelog fragment ## Deployment and Testing - [ ] Build docs locally to verify wiki-links resolve - [ ] Deploy via ArgoCD and verify at docs.ops.eblu.me/reference/ 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/88
2026-02-03 14:27:37 -08:00
## Infrastructure
Host inventory and network configuration.
Enforce unique doc filenames and simple wiki-links (#109) ## Summary - Rename section index files to match their titles (tutorials.md, reference.md, how-to.md, explanation.md) so all filenames are unique - Convert all ~47 path-based wiki-links to simple filename format across 15 files - Update doc-filenames task to no longer skip index.md files - Update doc-links task to reject path-based links containing '/' This ensures all wiki-links work correctly in obsidian.nvim by making links resolvable by filename alone. ## Testing - `mise run doc-filenames` - all unique - `mise run doc-links` - no broken or path-based links - `mise run doc-titles` - no duplicates Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/109
2026-02-04 17:21:34 -08:00
- [[hosts|Hosts]] - Device inventory
Convert wiki-link titles to lowercase slugs (#92) ## Summary - Convert all frontmatter titles to lowercase-hyphenated format (e.g., `grafana-alloy` instead of `Grafana Alloy`) - Update all wiki-links to use the new slug format - Update `doc-titles` task to validate slug format (lowercase, hyphens only) Quartz appears to require titles without spaces for wiki-link resolution. ## Deployment and Testing - [x] Pre-commit hooks pass (`doc-titles` and `doc-links`) - [ ] Build docs v1.0.8 and deploy - [ ] Verify wiki-links resolve correctly (e.g., `[[grafana-alloy]]`) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/92
2026-02-03 16:06:35 -08:00
- [[indri]] - Primary server
Polish ringtail NixOS config and add documentation (#208) ## Summary - Fix Super+Return keybinding to launch wezterm in sway - Set fish as default login shell - Remove `initialPassword` (real password already set) - Add 1Password CLI + GUI, chezmoi, and dev tool packages (neovim, eza, fd, fzf, zoxide, starship, atuin, bat, ripgrep) - Add ringtail reference card, update host inventory and reference index - Changelog fragment ## Post-merge deployment - `mise run provision-ringtail` to rebuild NixOS - On ringtail: launch 1Password GUI, enable CLI integration (Settings > Developer > CLI integration) - Chezmoi needs `.chezmoiignore` updates in the dotfiles repo (separate task) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/208
2026-02-18 17:53:47 -08:00
- [[ringtail]] - Service host & gaming PC
Convert wiki-link titles to lowercase slugs (#92) ## Summary - Convert all frontmatter titles to lowercase-hyphenated format (e.g., `grafana-alloy` instead of `Grafana Alloy`) - Update all wiki-links to use the new slug format - Update `doc-titles` task to validate slug format (lowercase, hyphens only) Quartz appears to require titles without spaces for wiki-link resolution. ## Deployment and Testing - [x] Pre-commit hooks pass (`doc-titles` and `doc-links`) - [ ] Build docs v1.0.8 and deploy - [ ] Verify wiki-links resolve correctly (e.g., `[[grafana-alloy]]`) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/92
2026-02-03 16:06:35 -08:00
- [[gilbert]] - Development workstation
- [[tailscale]] - ACLs, groups, tags
Add Gandi DNS docs and rewrite homepage intro (#115) ## Summary - New reference card (`docs/reference/infrastructure/gandi.md`) covering DNS records, Pulumi config, TLS integration - New how-to guide (`docs/how-to/gandi-operations.md`) for DNS deployment and PAT cycling with `pbpaste` shortcut - Rewritten homepage intro for wider audience ahead of public docs.eblu.me - Cross-linked from reference index, routing, caddy, and how-to index - Fixed PAT expiration inaccuracy in `pulumi/gandi/README.md` (max is 90 days, not 30) ## Test plan - [ ] Verify wiki-links resolve in Quartz build - [ ] Review gandi reference card for accuracy - [ ] Review gandi-operations how-to for accuracy - [ ] Check homepage reads well for external visitors Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/115
2026-02-07 21:02:10 -08:00
- [[gandi]] - DNS hosting for `eblu.me`
Add plan and reference card for UniFi Express 7 Pulumi stack (#145) ## Summary - Rewrites the UniFi Pulumi plan doc to use filipowm/unifi Terraform provider via `pulumi package add terraform-provider` (replaces pulumiverse_unifi approach) - Adds network segmentation goals (main/guest/IoT WiFi zones) and API key auth - Creates UniFi reference card (`docs/reference/infrastructure/unifi.md`) with topology diagram - Updates all documentation indexes (plans.md, how-to.md, hosts.md, reference.md) ## What's Deferred Actual stack scaffolding (`pulumi/unifi/`), mise tasks, and `pulumi import` are blocked on switch purchase and cabling. The plan doc captures everything needed for a future execution session. ## Verification - `docs-check-links` passes (all wiki-links resolve) - `docs-check-index` passes (unifi.md referenced in reference.md) - Pre-commit hooks pass Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/145
2026-02-10 15:36:13 -08:00
- [[unifi]] - Home WiFi router (UniFi Express 7)
Enforce unique doc filenames and simple wiki-links (#109) ## Summary - Rename section index files to match their titles (tutorials.md, reference.md, how-to.md, explanation.md) so all filenames are unique - Convert all ~47 path-based wiki-links to simple filename format across 15 files - Update doc-filenames task to no longer skip index.md files - Update doc-links task to reject path-based links containing '/' This ensures all wiki-links work correctly in obsidian.nvim by making links resolvable by filename alone. ## Testing - `mise run doc-filenames` - all unique - `mise run doc-links` - no broken or path-based links - `mise run doc-titles` - no duplicates Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/109
2026-02-04 17:21:34 -08:00
- [[routing|Routing]] - DNS domains, port mappings
Add power infrastructure reference card (#138) ## Summary - New `power.md` reference card documenting the full power chain: AC grid → Anker SOLIX F2000 battery → CyberPower CP1000PFCLCD UPS → homelab - Lists all devices on the UPS (indri, sifaka, UniFi Express 7, Starlink) - Replaced inline UPS entry on indri card with link to the new power card - Added power card to reference index Context: power chain was upgraded — the Anker battery station now sits between grid power and the UPS, providing extended runtime for grid outages. ## Test plan - [x] docs-check-links, docs-check-index, docs-check-filenames all pass 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/138
2026-02-09 23:03:13 -08:00
- [[power]] - Battery-backed power chain
Add reference/tools/ category with Dagger, ArgoCD CLI, Ansible, and Pulumi cards (#178) ## Summary - Create `docs/reference/tools/` with four reference cards: Dagger (build engine), ArgoCD CLI (deployment workflows), Ansible (config management), and Pulumi (DNS/Tailscale IaC) - Move `ansible/roles.md` → `tools/ansible.md`, broadened with CLI patterns and dry-run usage - Update `reference.md` index: add "Tools" section, remove old "Ansible" section - Update `update-documentation.md` to reflect Dagger build process (workflow steps, manual build recipe, runner environment) - Update `adopt-dagger-ci.md` plan to note how-to articles were handled via reference card + existing how-to updates - Fix all broken `[[roles]]` wiki-links across 5 files → `[[ansible]]` ## Verification - `docs-check-links` ✓ — no broken wiki-links - `docs-check-index` ✓ — all docs referenced in category index - `docs-check-filenames` ✓ — no duplicate filenames - All pre-commit hooks pass Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/178
2026-02-12 19:18:46 -08:00
## Tools
Build, deployment, and IaC tool reference.
Add mise-tasks reference card and include in ai-docs Categorized reference of all mise tasks with descriptions. Added to the tools section of the reference index and to the ai-docs context priming script. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-24 21:17:34 -08:00
- [[mise-tasks]] - Operational task runner (all `mise run` tasks)
Add reference/tools/ category with Dagger, ArgoCD CLI, Ansible, and Pulumi cards (#178) ## Summary - Create `docs/reference/tools/` with four reference cards: Dagger (build engine), ArgoCD CLI (deployment workflows), Ansible (config management), and Pulumi (DNS/Tailscale IaC) - Move `ansible/roles.md` → `tools/ansible.md`, broadened with CLI patterns and dry-run usage - Update `reference.md` index: add "Tools" section, remove old "Ansible" section - Update `update-documentation.md` to reflect Dagger build process (workflow steps, manual build recipe, runner environment) - Update `adopt-dagger-ci.md` plan to note how-to articles were handled via reference card + existing how-to updates - Fix all broken `[[roles]]` wiki-links across 5 files → `[[ansible]]` ## Verification - `docs-check-links` ✓ — no broken wiki-links - `docs-check-index` ✓ — all docs referenced in category index - `docs-check-filenames` ✓ — no duplicate filenames - All pre-commit hooks pass Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/178
2026-02-12 19:18:46 -08:00
- [[dagger]] - CI/CD build engine (Python SDK)
- [[argocd-cli]] - ArgoCD CLI workflows
- [[ansible]] - Configuration management for indri
- [[pulumi]] - Infrastructure-as-Code (DNS, Tailscale ACLs)
Phase 2: Add Reference section with 24 technical reference cards (#88) ## Summary - Create `docs/reference/` section with 24 technical reference cards - Services (16): alloy, argocd, borgmatic, 1password, forgejo, grafana, jellyfin, kiwix, loki, miniflux, navidrome, postgresql, prometheus, teslamate, transmission, zot - Infrastructure (3): hosts, tailscale, routing - Kubernetes (2): cluster, apps - Storage (2): sifaka, backups - Update README to mark Phase 2 as complete - Add towncrier changelog fragment ## Deployment and Testing - [ ] Build docs locally to verify wiki-links resolve - [ ] Deploy via ArgoCD and verify at docs.ops.eblu.me/reference/ 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/88
2026-02-03 14:27:37 -08:00
## Kubernetes
Cluster configuration and application registry.
Enforce unique doc filenames and simple wiki-links (#109) ## Summary - Rename section index files to match their titles (tutorials.md, reference.md, how-to.md, explanation.md) so all filenames are unique - Convert all ~47 path-based wiki-links to simple filename format across 15 files - Update doc-filenames task to no longer skip index.md files - Update doc-links task to reject path-based links containing '/' This ensures all wiki-links work correctly in obsidian.nvim by making links resolvable by filename alone. ## Testing - `mise run doc-filenames` - all unique - `mise run doc-links` - no broken or path-based links - `mise run doc-titles` - no duplicates Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/109
2026-02-04 17:21:34 -08:00
- [[cluster|Cluster]] - Minikube specs, storage, networking
- [[apps|Apps]] - ArgoCD application registry
Add Phase 3 tutorials with audience targeting (#94) ## Summary - Create tutorials directory structure with index page - Add 5 main tutorials targeting different audiences: - **what-is-blumeops** (Reader, AI) - High-level orientation - **exploring-the-docs** (All) - Navigation guide - **ai-assistance-guide** (AI, Owner) - Context for AI-assisted operations - **contributing** (Contributor) - First contribution workflow - **replicating-blumeops** (Replicator) - Overview for building similar setup - Add 4 replication sub-tutorials: - tailscale-setup, kubernetes-bootstrap, argocd-config, observability-stack - Update README.md to mark Phase 3 complete - Add changelog fragment Each tutorial explicitly identifies its target audiences and links to reference material rather than re-explaining concepts. ## Deployment and Testing - [x] All pre-commit hooks pass (doc-links validates wiki links) - [ ] Build docs via workflow to verify rendering - [ ] Review content for accuracy 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/94
2026-02-03 18:51:57 -08:00
- [[tailscale-operator]] - Tailscale ingress for k8s services
Convert wiki-link titles to lowercase slugs (#92) ## Summary - Convert all frontmatter titles to lowercase-hyphenated format (e.g., `grafana-alloy` instead of `Grafana Alloy`) - Update all wiki-links to use the new slug format - Update `doc-titles` task to validate slug format (lowercase, hyphens only) Quartz appears to require titles without spaces for wiki-link resolution. ## Deployment and Testing - [x] Pre-commit hooks pass (`doc-titles` and `doc-links`) - [ ] Build docs v1.0.8 and deploy - [ ] Verify wiki-links resolve correctly (e.g., `[[grafana-alloy]]`) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/92
2026-02-03 16:06:35 -08:00
- [[external-secrets]] - Secrets management
Phase 2: Add Reference section with 24 technical reference cards (#88) ## Summary - Create `docs/reference/` section with 24 technical reference cards - Services (16): alloy, argocd, borgmatic, 1password, forgejo, grafana, jellyfin, kiwix, loki, miniflux, navidrome, postgresql, prometheus, teslamate, transmission, zot - Infrastructure (3): hosts, tailscale, routing - Kubernetes (2): cluster, apps - Storage (2): sifaka, backups - Update README to mark Phase 2 as complete - Add towncrier changelog fragment ## Deployment and Testing - [ ] Build docs locally to verify wiki-links resolve - [ ] Deploy via ArgoCD and verify at docs.ops.eblu.me/reference/ 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/88
2026-02-03 14:27:37 -08:00
## Storage
Network storage and backup configuration.
Enforce unique doc filenames and simple wiki-links (#109) ## Summary - Rename section index files to match their titles (tutorials.md, reference.md, how-to.md, explanation.md) so all filenames are unique - Convert all ~47 path-based wiki-links to simple filename format across 15 files - Update doc-filenames task to no longer skip index.md files - Update doc-links task to reject path-based links containing '/' This ensures all wiki-links work correctly in obsidian.nvim by making links resolvable by filename alone. ## Testing - `mise run doc-filenames` - all unique - `mise run doc-links` - no broken or path-based links - `mise run doc-titles` - no duplicates Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/109
2026-02-04 17:21:34 -08:00
- [[sifaka|Sifaka]] - Synology NAS configuration
Convert wiki-link titles to lowercase slugs (#92) ## Summary - Convert all frontmatter titles to lowercase-hyphenated format (e.g., `grafana-alloy` instead of `Grafana Alloy`) - Update all wiki-links to use the new slug format - Update `doc-titles` task to validate slug format (lowercase, hyphens only) Quartz appears to require titles without spaces for wiki-link resolution. ## Deployment and Testing - [x] Pre-commit hooks pass (`doc-titles` and `doc-links`) - [ ] Build docs v1.0.8 and deploy - [ ] Verify wiki-links resolve correctly (e.g., `[[grafana-alloy]]`) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/92
2026-02-03 16:06:35 -08:00
- [[postgresql-storage]] - Database cluster
Enforce unique doc filenames and simple wiki-links (#109) ## Summary - Rename section index files to match their titles (tutorials.md, reference.md, how-to.md, explanation.md) so all filenames are unique - Convert all ~47 path-based wiki-links to simple filename format across 15 files - Update doc-filenames task to no longer skip index.md files - Update doc-links task to reject path-based links containing '/' This ensures all wiki-links work correctly in obsidian.nvim by making links resolvable by filename alone. ## Testing - `mise run doc-filenames` - all unique - `mise run doc-links` - no broken or path-based links - `mise run doc-titles` - no duplicates Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/109
2026-02-04 17:21:34 -08:00
- [[backups|Backups]] - Backup policy and schedule
Phase 2: Add Reference section with 24 technical reference cards (#88) ## Summary - Create `docs/reference/` section with 24 technical reference cards - Services (16): alloy, argocd, borgmatic, 1password, forgejo, grafana, jellyfin, kiwix, loki, miniflux, navidrome, postgresql, prometheus, teslamate, transmission, zot - Infrastructure (3): hosts, tailscale, routing - Kubernetes (2): cluster, apps - Storage (2): sifaka, backups - Update README to mark Phase 2 as complete - Add towncrier changelog fragment ## Deployment and Testing - [ ] Build docs locally to verify wiki-links resolve - [ ] Deploy via ArgoCD and verify at docs.ops.eblu.me/reference/ 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/88
2026-02-03 14:27:37 -08:00
## Operations
Operational concerns and their components.
Convert wiki-link titles to lowercase slugs (#92) ## Summary - Convert all frontmatter titles to lowercase-hyphenated format (e.g., `grafana-alloy` instead of `Grafana Alloy`) - Update all wiki-links to use the new slug format - Update `doc-titles` task to validate slug format (lowercase, hyphens only) Quartz appears to require titles without spaces for wiki-link resolution. ## Deployment and Testing - [x] Pre-commit hooks pass (`doc-titles` and `doc-links`) - [ ] Build docs v1.0.8 and deploy - [ ] Verify wiki-links resolve correctly (e.g., `[[grafana-alloy]]`) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/92
2026-02-03 16:06:35 -08:00
- [[observability]] - Metrics, logs, dashboards
- [[backup]] - Data protection
- [[disaster-recovery]] - Recovery procedures (TBD)
Reference in a new issue Copy permalink