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

124 lines
4.5 KiB
Markdown
Raw Normal View History

Add Phase 4: how-to guides documentation (#95) ## Summary - Create `docs/how-to/` directory with index and four how-to guides - deploy-k8s-service: Quick reference for Kubernetes deployments via ArgoCD - add-ansible-role: Adding new Ansible roles for indri services - update-tailscale-acls: Modifying Tailscale ACL policies via Pulumi - troubleshooting: Diagnosing and fixing common issues - Update exploring-the-docs to include How-to section links - Update README.md to mark Phase 4 as complete ## 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/95
2026-02-03 20:17:24 -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: How-To
Update ringtail flake inputs, add flake-update pipeline (#240) ## Summary - Update all ringtail NixOS flake inputs (nixpkgs, disko, home-manager) to latest - Add `flake_update` Dagger function (`nix flake update`) alongside existing `flake_lock` (`nix flake lock`) - Add how-to guide for managing the ringtail lockfile - Update dagger and ringtail reference cards ## Deployment and Testing - [x] `mise run provision-ringtail` — deployed successfully, `changed=2` (repo + rebuild) - [x] `mise run services-check` — all services healthy - [x] Doc link and index checks pass Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/240
2026-02-22 08:17:52 -08:00
modified: 2026-02-22
Add Phase 4: how-to guides documentation (#95) ## Summary - Create `docs/how-to/` directory with index and four how-to guides - deploy-k8s-service: Quick reference for Kubernetes deployments via ArgoCD - add-ansible-role: Adding new Ansible roles for indri services - update-tailscale-acls: Modifying Tailscale ACL policies via Pulumi - troubleshooting: Diagnosing and fixing common issues - Update exploring-the-docs to include How-to section links - Update README.md to mark Phase 4 as complete ## 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/95
2026-02-03 20:17:24 -08:00
tags:
- how-to
---
# How-To Guides
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
Task-oriented instructions for common BlumeOps operations. These guides assume you already understand the basic concepts - see [[tutorials|Tutorials]] if you're learning.
Add Phase 4: how-to guides documentation (#95) ## Summary - Create `docs/how-to/` directory with index and four how-to guides - deploy-k8s-service: Quick reference for Kubernetes deployments via ArgoCD - add-ansible-role: Adding new Ansible roles for indri services - update-tailscale-acls: Modifying Tailscale ACL policies via Pulumi - troubleshooting: Diagnosing and fixing common issues - Update exploring-the-docs to include How-to section links - Update README.md to mark Phase 4 as complete ## 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/95
2026-02-03 20:17:24 -08:00
## Deployment
| Guide | Description |
|-------|-------------|
| [[deploy-k8s-service]] | Deploy a new service to Kubernetes via ArgoCD |
| [[add-ansible-role]] | Add a new Ansible role for indri services |
Add release artifact workflow how-to and changelog fragments (#170) ## Summary - How-to guide for creating release artifact workflows with Forgejo packages - Changelog fragment for the multi-repo forgejo_actions_secrets Ansible role change - Changelog fragment for the new docs 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/170
2026-02-12 11:20:05 -08:00
| [[create-release-artifact-workflow]] | Build artifacts and publish to Forgejo packages |
Document container build pattern and port navidrome (#192) ## Summary - Add how-to guide (`docs/how-to/build-container-image.md`) covering the full container build workflow: directory layout, Dagger local builds, mise release task, and common patterns with links to existing containers - Port navidrome from upstream `deluan/navidrome:0.60.3` to a custom three-stage build (`containers/navidrome/Dockerfile`) using Node + Go + Alpine - Update navidrome deployment to use `registry.ops.eblu.me/blumeops/navidrome:v1.0.0` ## Deployment and Testing - [x] `dagger call build --src=. --container-name=navidrome` builds successfully - [ ] After merge: `mise run container-tag-and-release navidrome v1.0.0` - [ ] After image published: `argocd app sync navidrome` and verify pod starts Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/192
2026-02-15 08:05:11 -08:00
| [[build-container-image]] | Build and release a custom container image via Dagger |
Add Phase 4: how-to guides documentation (#95) ## Summary - Create `docs/how-to/` directory with index and four how-to guides - deploy-k8s-service: Quick reference for Kubernetes deployments via ArgoCD - add-ansible-role: Adding new Ansible roles for indri services - update-tailscale-acls: Modifying Tailscale ACL policies via Pulumi - troubleshooting: Diagnosing and fixing common issues - Update exploring-the-docs to include How-to section links - Update README.md to mark Phase 4 as complete ## 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/95
2026-02-03 20:17:24 -08:00
## Configuration
| Guide | Description |
|-------|-------------|
| [[update-tailscale-acls]] | Update Tailscale access control policies |
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-operations]] | Manage DNS records and cycle the Gandi API token |
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
| [[use-pypi-proxy]] | Configure pip and publish packages to devpi |
docs/expose-service-publicly pt2 - fly.io (#119) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/119
2026-02-08 00:38:27 -08:00
| [[expose-service-publicly]] | Expose a service to the public internet via Fly.io + Tailscale |
Add authenticated GitHub PAT for Forgejo mirror sync (#269) ## Summary - **mirror-create**: Auto-includes GitHub PAT from 1Password for authenticated upstream fetches at mirror creation time - **mirror-update-pats**: New mise task that SSHes into indri and rewrites the git remote URL in every GitHub mirror's bare repo config to embed the PAT. Idempotent, supports `--dry-run` - **app.ini.j2**: Explicit `[mirror]` section with `DEFAULT_INTERVAL = 8h` and `MIN_INTERVAL = 10m` (bakes in the defaults for visibility) - **manage-forgejo-mirrors**: New how-to doc covering mirror creation, PAT storage, the `mirror-update-pats` task, and the full 20-day PAT rotation procedure ## Context GitHub tightened unauthenticated rate limits for git clone/fetch in May 2025. With 23 GitHub mirrors syncing every 8 hours, authenticated fetches avoid throttling. The PAT is stored in 1Password (`Forgejo Secrets` → `github-mirror-pat`) and has been applied to all existing mirrors. ## Deployment and Testing - [x] `mirror-update-pats` dry-run verified (23 mirrors detected) - [x] `mirror-update-pats` applied to all 23 GitHub mirrors on indri - [x] Idempotency confirmed (re-run shows 0 updated, 23 skipped) - [ ] Provision indri with `--tags forgejo` to apply `[mirror]` config - [ ] Trigger a manual mirror sync and verify success in Forgejo UI Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/269
2026-02-25 20:20:23 -08:00
| [[manage-forgejo-mirrors]] | Create mirrors, update PATs, and rotate GitHub credentials |
Add Phase 4: how-to guides documentation (#95) ## Summary - Create `docs/how-to/` directory with index and four how-to guides - deploy-k8s-service: Quick reference for Kubernetes deployments via ArgoCD - add-ansible-role: Adding new Ansible roles for indri services - update-tailscale-acls: Modifying Tailscale ACL policies via Pulumi - troubleshooting: Diagnosing and fixing common issues - Update exploring-the-docs to include How-to section links - Update README.md to mark Phase 4 as complete ## 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/95
2026-02-03 20:17:24 -08:00
| [[update-documentation]] | Publish docs via build-blumeops workflow |
Switch git hooks from pre-commit to prek prek is a faster, Rust-native drop-in replacement for pre-commit. Migrates config from .pre-commit-config.yaml to prek.toml, adds built-in checks for case conflicts, private key detection, and executable shebangs. Updates all doc references. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-02 18:14:03 -08:00
| [[update-tooling-dependencies]] | Monthly update cycle for prek hooks, Fly, mise, and workflow deps |
Add Phase 4: how-to guides documentation (#95) ## Summary - Create `docs/how-to/` directory with index and four how-to guides - deploy-k8s-service: Quick reference for Kubernetes deployments via ArgoCD - add-ansible-role: Adding new Ansible roles for indri services - update-tailscale-acls: Modifying Tailscale ACL policies via Pulumi - troubleshooting: Diagnosing and fixing common issues - Update exploring-the-docs to include How-to section links - Update README.md to mark Phase 4 as complete ## 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/95
2026-02-03 20:17:24 -08:00
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
## Knowledge Base
| Guide | Description |
|-------|-------------|
| [[review-documentation]] | Periodically review and maintain documentation |
Add service version review system (#196) ## Summary - Add `service-versions.yaml` tracking file with 33 services and upstream release URLs - Add `mise run service-review` task (Python uv script) mirroring the docs-review UX - Add `review-services` how-to article covering the review process by service type - Add `[[review-services]]` link to the how-to index Knowledge Base table ## Deployment and Testing - [x] `mise run service-review` displays 33 services, all "never reviewed" - [x] `mise run service-review -- --type ansible` filters to 7 Ansible services - [x] `mise run service-review -- --limit 5` shows 5 rows - [x] `mise run docs-check-links` — no broken wiki-links - [x] `mise run docs-check-frontmatter` — new doc passes validation - [x] All pre-commit hooks pass Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/196
2026-02-16 17:02:56 -08:00
| [[review-services]] | Periodically review services for version freshness |
Formalize C0/C1/C2 change classification (#259) ## Summary - **C0 (Quick Fix):** Now explicitly allows direct-to-main commits with no PR required — for low-risk, fix-forward-safe changes - **C1 (Human Review):** New docs-first workflow with branch deployment (ArgoCD `--revision`, Ansible from checkout). Includes upgrade criteria for escalation to C2 - **C2 (Mikado Chain):** Introduces the **Mikado Branch Invariant** — strict commit ordering where card-introducing commits come first, followed by code progress, followed by card closures. Branch resets required when new prerequisites are discovered Updates CLAUDE.md rules (3, 4, 8, 9) to reflect that C0 bypasses branching/PR requirements. Also updates ai-assistance-guide, how-to index, and docs-mikado task description. ## Files changed - `CLAUDE.md` — rules and classification table - `docs/how-to/agent-change-process.md` — full process rewrite - `docs/tutorials/ai-assistance-guide.md` — branching and pitfalls sections - `docs/how-to/how-to.md` — index description - `mise-tasks/docs-mikado` — task description - `docs/changelog.d/formalize-change-classification.doc.md` — changelog fragment Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/259
2026-02-23 16:19:54 -08:00
| [[agent-change-process]] | C0/C1/C2 change classification and Mikado Branch Invariant |
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
Add Phase 4: how-to guides documentation (#95) ## Summary - Create `docs/how-to/` directory with index and four how-to guides - deploy-k8s-service: Quick reference for Kubernetes deployments via ArgoCD - add-ansible-role: Adding new Ansible roles for indri services - update-tailscale-acls: Modifying Tailscale ACL policies via Pulumi - troubleshooting: Diagnosing and fixing common issues - Update exploring-the-docs to include How-to section links - Update README.md to mark Phase 4 as complete ## 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/95
2026-02-03 20:17:24 -08:00
## Operations
| Guide | Description |
|-------|-------------|
Review gandi-operations doc and reorganize how-to guides (#200) ## Summary - **Doc review:** Reviewed `gandi-operations.md` — added `last-reviewed` frontmatter, verified all wiki-links, confirmed Pulumi state has no drift - **Gandi reference fix:** Added missing `cv.eblu.me` CNAME row to `gandi.md` DNS records table (was present in Pulumi but undocumented) - **Pulumi comment fix:** Updated stale `README.md` reference in `__main__.py` to point to `docs/how-to/gandi-operations.md` - **How-to reorg:** Moved 14 how-to guides into 3 subdirectories (`deployment/`, `configuration/`, `operations/`), collapsed the Documentation and Database index sections into Configuration and Operations respectively ## Verification - `docs-check-links` — all 180 wiki-links valid - `docs-check-filenames` — all 90 filenames unique - `dns-preview` — 5 resources unchanged, no drift - All pre-commit hooks pass ## Test plan - [ ] Verify docs site builds correctly with new paths - [ ] Spot-check a few wiki-links from other pages to moved how-to guides Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/200
2026-02-17 07:29:33 -08:00
| [[connect-to-postgres]] | Connect to PostgreSQL as a superuser via psql |
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
| [[restart-indri]] | Safely shut down and restart indri |
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
| [[manage-flyio-proxy]] | Deploy, shutoff, and troubleshoot the public proxy |
Add how-to guide for restoring 1Password backup from borgmatic (#141) ## Summary - New how-to guide at `docs/how-to/restore-1password-backup.md` with step-by-step procedure for extracting and decrypting a 1Password `.1pux` export from borgmatic backup - **End-to-end verified**: extracted from today's borg archive, decrypted age key with openssl, decrypted .1pux with age → valid 31MB zip with vault data - Cross-links added from: disaster-recovery, 1password, borgmatic, backups policy, and how-to index - Updated disaster-recovery.md from TBD stub to include a procedures table ## Deployment and Testing - [x] Verified full extraction + decryption flow against live borgmatic archive - [x] `docs-check-links` passes — all wiki-links valid - [ ] Review guide for clarity and completeness Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/141
2026-02-10 10:55:00 -08:00
| [[restore-1password-backup]] | Recover 1Password credentials from borgmatic backup |
Add Phase 4: how-to guides documentation (#95) ## Summary - Create `docs/how-to/` directory with index and four how-to guides - deploy-k8s-service: Quick reference for Kubernetes deployments via ArgoCD - add-ansible-role: Adding new Ansible roles for indri services - update-tailscale-acls: Modifying Tailscale ACL policies via Pulumi - troubleshooting: Diagnosing and fixing common issues - Update exploring-the-docs to include How-to section links - Update README.md to mark Phase 4 as complete ## 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/95
2026-02-03 20:17:24 -08:00
| [[troubleshooting]] | Diagnose and fix common issues |
Add migration plan for Forgejo brew-to-source transition (#140) ## Summary - Add `docs/how-to/plans/migrate-forgejo-from-brew.md` — full Diataxis-style plan covering background, one-time migration steps, Ansible role changes (with exact code), verification checklist, and future considerations - Add `docs/how-to/plans/plans.md` — new plans subdirectory index for upcoming migration/transition plans - Update `docs/how-to/how-to.md` with a Plans section - Update `docs/tutorials/exploring-the-docs.md` to mention plans in the doc structure table and quick-path sections for Owner and AI audiences ## Test plan - [x] `docs-check-links` passes - [x] `docs-check-index` passes - [x] All pre-commit hooks pass Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/140
2026-02-10 10:18:53 -08:00
## Plans
Migration and transition plans for upcoming infrastructure changes.
| Plan | Description |
|------|-------------|
| [[plans]] | Index of all plans |
Close Dagger CI plan (Phases 1-3 complete) (#165) ## Summary - Move `adopt-dagger-ci.md` to new `docs/how-to/plans/completed/` archive - Update plan status to "Phases 1–3 complete" with all verification checklists checked - Update runner description to reflect what actually stayed (Docker CLI, Node.js needed) - Document known issue: changelog dates still show UTC - Create completed plans index, update plans and how-to indexes - Changelog fragment 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/165
2026-02-11 18:04:39 -08:00
| [[completed]] | Completed plans archive |
Add migration plan for Forgejo brew-to-source transition (#140) ## Summary - Add `docs/how-to/plans/migrate-forgejo-from-brew.md` — full Diataxis-style plan covering background, one-time migration steps, Ansible role changes (with exact code), verification checklist, and future considerations - Add `docs/how-to/plans/plans.md` — new plans subdirectory index for upcoming migration/transition plans - Update `docs/how-to/how-to.md` with a Plans section - Update `docs/tutorials/exploring-the-docs.md` to mention plans in the doc structure table and quick-path sections for Owner and AI audiences ## Test plan - [x] `docs-check-links` passes - [x] `docs-check-index` passes - [x] All pre-commit hooks pass Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/140
2026-02-10 10:18:53 -08:00
| [[migrate-forgejo-from-brew]] | Transition Forgejo from Homebrew to source-built binary |
Abandon UniFi IaC, add manual network segmentation plan (#189) ## Summary - Abandon the UniFi Pulumi IaC approach after provider bugs caused a network outage (no-op update reset undeclared properties on the default LAN network) - Remove untracked IaC artifacts (`pulumi/unifi/`, `mise-tasks/unifi-preview`, `mise-tasks/unifi-up`) locally - Mark `add-unifi-pulumi-stack` plan as Abandoned with explanation - Create new `segment-home-network` plan for manual three-network segmentation (Main/IoT/Guest) via UX7 web UI - Rewrite UniFi reference card to remove all Pulumi/IaC references - Update plan and how-to indexes ## Test plan - [x] `docs-check-links` passes - [x] `docs-check-index` passes - [x] Pre-commit hooks pass - [ ] Review segmentation plan for completeness before executing manually 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/189
2026-02-14 09:47:04 -08:00
| [[add-unifi-pulumi-stack]] | Add Pulumi IaC for UniFi Express 7 (abandoned) |
| [[segment-home-network]] | Manual three-network segmentation for UniFi Express 7 |
Add plans for Dagger CI/CD and upstream fork strategy (#150) ## Summary Two new plan documents in `docs/how-to/plans/`: - **adopt-dagger-ci** — Migrate CI/CD build logic from Forgejo Actions YAML to Dagger (Python SDK). Forgejo Actions stays as a thin trigger layer. Covers: - Container builds with local iteration (`dagger call build ... terminal`) - Docs builds with Forgejo packages migration (replacing Forgejo releases) - Runner simplification (only Docker + dagger CLI needed) - Secrets handling via Dagger's `Secret` type - Future: forked project builds, Python packages, pre-merge validation - **upstream-fork-strategy** — Stacked-branch pattern for maintaining forks of upstream projects. Covers: - Daily automated rebase with conflict detection and issue creation - Branch model: `upstream/main` → `blumeops` → `feature/*` - Quartz fork as first instance, enabling `last-reviewed` frontmatter rendering in docs - Upstream PR path for contributing changes back ## Context These plans emerged from evaluating alternatives to the GHA ecosystem (BuildKite, Concourse, Earthly) for CI/CD. Dagger was chosen for its local iteration story, Python-native pipelines, and zero-infrastructure requirements. The fork strategy is a prerequisite for customizing Quartz and other upstream tools. Neither plan is ready for execution yet — they are design documents for future work. Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/150
2026-02-11 10:20:14 -08:00
| [[adopt-dagger-ci]] | Adopt Dagger as CI/CD build engine |
| [[upstream-fork-strategy]] | Stacked-branch forking strategy for upstream projects |
Transcribe backlog tasks into plan documents (#151) ## Summary - **adopt-oidc-provider:** Dex-based OIDC identity provider for SSO across services (status: Planning — service dependency/recovery design needed) - **harden-zot-registry:** OIDC + API key auth and tag immutability for zot (depends on OIDC provider + Dagger CI) - **forgejo-actions-dashboard:** Custom textfile Prometheus exporter + Grafana dashboard for Forgejo Actions CI metrics - **operationalize-reolink-camera:** Cloud-free Frigate NVR with ONNX detection, NFS ring buffer recording to sifaka (depends on network segmentation) - **add-unifi-pulumi-stack:** Expanded with NFS security motivation, BlumeOps Services subnet, IoT/appliance segregation, firewall rules ## Test plan - [x] Pre-commit hooks pass (all 3 commits) - [x] `docs-check-links` passes - [x] `docs-check-index` passes - [x] `docs-check-filenames` passes 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/151
2026-02-11 11:47:23 -08:00
| [[adopt-oidc-provider]] | Deploy OIDC identity provider for SSO across services |
Review Grafana: replace Helm upgrade plan with C2 Mikado chain (#258) ## Summary - Delete the old 3-phase Helm chart upgrade plan (predates Mikado system) - Create C2 Mikado chain with goal card `upgrade-grafana` and two leaf prereqs: - `kustomize-grafana-deployment` — convert Helm to kustomize manifests - `build-grafana-container` — home-built Grafana 12.x image (no upstream containers) - Record first-ever Grafana review: currently at v11.4.0 on Helm chart 8.8.2 - Update service-versions.yaml, how-to index, and plans index ## Service Review Findings - Grafana is healthy and synced in ArgoCD - Running v11.4.0, latest upstream is 12.3.3 - Breaking changes for 12.x are low-risk (React panels only, UIDs compliant) - PVC is disposable — dashboards and datasources are all config-provisioned ## Deployment and Testing - [ ] No deployment needed — documentation-only change - [ ] `docs-check-links` passes - [ ] `docs-check-index` passes Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/258
2026-02-23 15:06:00 -08:00
| [[upgrade-grafana]] | Upgrade Grafana to 12.x with kustomize and home-built container |
Transcribe backlog tasks into plan documents (#151) ## Summary - **adopt-oidc-provider:** Dex-based OIDC identity provider for SSO across services (status: Planning — service dependency/recovery design needed) - **harden-zot-registry:** OIDC + API key auth and tag immutability for zot (depends on OIDC provider + Dagger CI) - **forgejo-actions-dashboard:** Custom textfile Prometheus exporter + Grafana dashboard for Forgejo Actions CI metrics - **operationalize-reolink-camera:** Cloud-free Frigate NVR with ONNX detection, NFS ring buffer recording to sifaka (depends on network segmentation) - **add-unifi-pulumi-stack:** Expanded with NFS security motivation, BlumeOps Services subnet, IoT/appliance segregation, firewall rules ## Test plan - [x] Pre-commit hooks pass (all 3 commits) - [x] `docs-check-links` passes - [x] `docs-check-index` passes - [x] `docs-check-filenames` passes 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/151
2026-02-11 11:47:23 -08:00
| [[operationalize-reolink-camera]] | Cloud-free NVR with Frigate and ring buffer recording |
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
Update ringtail flake inputs, add flake-update pipeline (#240) ## Summary - Update all ringtail NixOS flake inputs (nixpkgs, disko, home-manager) to latest - Add `flake_update` Dagger function (`nix flake update`) alongside existing `flake_lock` (`nix flake lock`) - Add how-to guide for managing the ringtail lockfile - Update dagger and ringtail reference cards ## Deployment and Testing - [x] `mise run provision-ringtail` — deployed successfully, `changed=2` (repo + rebuild) - [x] `mise run services-check` — all services healthy - [x] Doc link and index checks pass Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/240
2026-02-22 08:17:52 -08:00
## Ringtail
| Guide | Description |
|-------|-------------|
| [[manage-lockfile]] | Update or lock NixOS flake inputs via Dagger |
Create C2 Mikado cards for harden-zot-registry (#229) ## Summary - Replace the old pre-Mikado plan doc (`docs/how-to/plans/harden-zot-registry.md`) with a proper C2 Mikado chain in `docs/how-to/zot/` - Root goal: `harden-zot-registry` — enable OIDC + API key auth on zot with anonymous pull preserved - Three leaf prereqs: `register-zot-oidc-client`, `wire-ci-registry-auth`, `enforce-tag-immutability` - Add Zot section to `how-to.md` index, remove plan entry from plans index - All doc checks pass (`docs-check-links`, `docs-check-index`, `docs-mikado`) ## Changes - **New:** `docs/how-to/zot/harden-zot-registry.md` — C2 Mikado root goal - **New:** `docs/how-to/zot/register-zot-oidc-client.md` — Register OIDC client in Authentik - **New:** `docs/how-to/zot/wire-ci-registry-auth.md` — Wire CI push paths with registry auth - **New:** `docs/how-to/zot/enforce-tag-immutability.md` — Prevent version tag overwrites - **Deleted:** `docs/how-to/plans/harden-zot-registry.md` — Old plan doc (content absorbed into Mikado cards) - **Updated:** `docs/how-to/how-to.md` — Add Zot section, remove plan entry - **Updated:** `docs/how-to/plans/plans.md` — Remove plan entry 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/229
2026-02-20 17:56:25 -08:00
## Zot
Mikado chain for hardening the zot registry. Track progress with `mise run docs-mikado harden-zot-registry`.
- [[harden-zot-registry]]
- [[register-zot-oidc-client]]
- [[wire-ci-registry-auth]]
- [[enforce-tag-immutability]]
Add commit-based container tagging prereq to harden-zot-registry chain (#230) ## Summary - New Mikado card: `adopt-commit-based-container-tags` — replaces git-tag-triggered container builds with path-based main-branch triggers and manual workflow dispatch - Image tags become `vX.Y.Z-<sha>` (with `-main` suffix for main branch builds, `-nix` for Nix builds), tying versions to the actual bundled app version and exact source commit - `container-tag-and-release` mise task to be renamed to `container-build-and-release`, triggering workflow dispatch with the current HEAD SHA - Added as soft prereq to `harden-zot-registry` Mikado chain ## Test plan - [x] Pre-commit hooks pass (docs-check-index, docs-check-links, etc.) - [ ] Review card content for completeness 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/230
2026-02-20 18:26:27 -08:00
- [[adopt-commit-based-container-tags]]
Harden zot registry, pt 1 (#231) ## Summary - Enable OIDC + API key authentication on zot with anonymous pull preserved - Enforce tag immutability for version tags - Adopt commit-SHA-based container image tagging Details in the [[harden-zot-registry]] Mikado chain (`mise run docs-mikado harden-zot-registry`). ## Test plan - [ ] Anonymous pull still works - [ ] Unauthenticated push fails (401) - [ ] CI container builds pass with new auth and tagging - [ ] `mise run services-check` passes 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/231
2026-02-20 22:50:01 -08:00
- [[add-container-version-sync-check]]
Add install-dagger-on-nix-runner Mikado card (#233) ## Summary - New Mikado card: the ringtail nix-container-builder runner lacks dagger, which the nix workflow needs for `dagger call nix-version` (authentik version extraction fallback) - Re-opens `adopt-commit-based-container-tags` with this new prerequisite - All other containers (11 Dockerfile-only, nettest + ntfy with nix) build fine — only authentik's nix build is blocked ## Deployment and Testing - Docs only, no deployment needed Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/233
2026-02-20 23:03:12 -08:00
- [[install-dagger-on-nix-runner]]
Harden zot registry, pt 1 (#231) ## Summary - Enable OIDC + API key authentication on zot with anonymous pull preserved - Enforce tag immutability for version tags - Adopt commit-SHA-based container image tagging Details in the [[harden-zot-registry]] Mikado chain (`mise run docs-mikado harden-zot-registry`). ## Test plan - [ ] Anonymous pull still works - [ ] Unauthenticated push fails (401) - [ ] CI container builds pass with new auth and tagging - [ ] `mise run services-check` passes 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/231
2026-02-20 22:50:01 -08:00
- [[pin-container-versions]]
- [[add-dagger-nix-build]]
- [[fix-ntfy-nix-version]]
Create C2 Mikado cards for harden-zot-registry (#229) ## Summary - Replace the old pre-Mikado plan doc (`docs/how-to/plans/harden-zot-registry.md`) with a proper C2 Mikado chain in `docs/how-to/zot/` - Root goal: `harden-zot-registry` — enable OIDC + API key auth on zot with anonymous pull preserved - Three leaf prereqs: `register-zot-oidc-client`, `wire-ci-registry-auth`, `enforce-tag-immutability` - Add Zot section to `how-to.md` index, remove plan entry from plans index - All doc checks pass (`docs-check-links`, `docs-check-index`, `docs-mikado`) ## Changes - **New:** `docs/how-to/zot/harden-zot-registry.md` — C2 Mikado root goal - **New:** `docs/how-to/zot/register-zot-oidc-client.md` — Register OIDC client in Authentik - **New:** `docs/how-to/zot/wire-ci-registry-auth.md` — Wire CI push paths with registry auth - **New:** `docs/how-to/zot/enforce-tag-immutability.md` — Prevent version tag overwrites - **Deleted:** `docs/how-to/plans/harden-zot-registry.md` — Old plan doc (content absorbed into Mikado cards) - **Updated:** `docs/how-to/how-to.md` — Add Zot section, remove plan entry - **Updated:** `docs/how-to/plans/plans.md` — Remove plan entry 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/229
2026-02-20 17:56:25 -08:00
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
Mikado chain for deploying Authentik. Track progress with `mise run docs-mikado deploy-authentik`.
- [[deploy-authentik]]
- [[build-authentik-container]]
- [[provision-authentik-database]]
- [[create-authentik-secrets]]
- [[migrate-grafana-to-authentik]]
Upgrade k8s forgejo-runner from v6.3.1 to v12.x (#249) ## Summary - C2 Mikado chain for upgrading the k8s forgejo-runner daemon (6 major versions behind) - Root goal card with two leaf prerequisites: workflow validation and config review - Ringtail runner is already at ~v12.6.4 via nixpkgs, no work needed there ## Mikado Chain ``` upgrade-k8s-runner (goal) ├── validate-workflows-against-v12 (leaf) └── review-runner-config-v12 (leaf) ``` Both leaves are actionable now. The biggest risk is workflow schema validation (introduced in v8/v9) rejecting our existing workflows. ## Next Steps Work the leaf nodes in a follow-up session, then attempt the goal. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/249
2026-02-22 17:12:45 -08:00
Start C2 Mikado chain: build authentik from source Create goal card and 4 prerequisite cards for building authentik from a custom Nix derivation instead of using pkgs.authentik from nixpkgs. This removes the dependency on the nixpkgs packaging timeline and gives full version control over authentik releases. Chain: mikado/authentik-source-build Leaf nodes: authentik-api-client-generation, authentik-python-backend-derivation Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-28 08:20:17 -08:00
## Authentik Source Build
Mikado chain for building Authentik from a custom Nix derivation (from source). Track progress with `mise run docs-mikado build-authentik-from-source`.
- [[build-authentik-from-source]]
C2: Build authentik from source (Mikado chain) (#274) ## Mikado Chain: build-authentik-from-source Replace `pkgs.authentik` from nixpkgs with a custom Nix derivation built from source. This removes the dependency on the nixpkgs packaging timeline and gives full version control. Target version: **2025.12.4** (nixpkgs reference, upgrading from deployed 2025.10.1). ### Dependency Graph ``` build-authentik-from-source (goal) ├── authentik-go-server-derivation │ ├── authentik-api-client-generation ← IN PROGRESS │ └── authentik-python-backend-derivation ├── authentik-web-ui-derivation │ └── authentik-api-client-generation ← IN PROGRESS └── authentik-python-backend-derivation ``` ### Ready Leaves - `authentik-api-client-generation` — Go + TypeScript client generation from OpenAPI schema - `authentik-python-backend-derivation` — Django backend with 60+ deps, 4 in-tree packages ### Architecture Ported from [nixpkgs `pkgs/by-name/au/authentik/package.nix`](https://github.com/NixOS/nixpkgs/tree/master/pkgs/by-name/au/authentik): - `source.nix` — shared version/source fetch - `client-go.nix` — Go API client generation - `client-ts.nix` — TypeScript API client generation - `api-go-vendor-hook.nix` — Go vendor directory injection hook - (more components to follow as leaves are closed) ### Related Cards - [[build-authentik-from-source]] — Goal card - [[authentik-api-client-generation]] - [[authentik-python-backend-derivation]] - [[authentik-web-ui-derivation]] - [[authentik-go-server-derivation]] Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/274
2026-03-01 13:45:00 -08:00
- [[mirror-authentik-build-deps]]
Start C2 Mikado chain: build authentik from source Create goal card and 4 prerequisite cards for building authentik from a custom Nix derivation instead of using pkgs.authentik from nixpkgs. This removes the dependency on the nixpkgs packaging timeline and gives full version control over authentik releases. Chain: mikado/authentik-source-build Leaf nodes: authentik-api-client-generation, authentik-python-backend-derivation Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-28 08:20:17 -08:00
- [[authentik-api-client-generation]]
- [[authentik-python-backend-derivation]]
- [[authentik-web-ui-derivation]]
- [[authentik-go-server-derivation]]
Review Grafana: replace Helm upgrade plan with C2 Mikado chain (#258) ## Summary - Delete the old 3-phase Helm chart upgrade plan (predates Mikado system) - Create C2 Mikado chain with goal card `upgrade-grafana` and two leaf prereqs: - `kustomize-grafana-deployment` — convert Helm to kustomize manifests - `build-grafana-container` — home-built Grafana 12.x image (no upstream containers) - Record first-ever Grafana review: currently at v11.4.0 on Helm chart 8.8.2 - Update service-versions.yaml, how-to index, and plans index ## Service Review Findings - Grafana is healthy and synced in ArgoCD - Running v11.4.0, latest upstream is 12.3.3 - Breaking changes for 12.x are low-risk (React panels only, UIDs compliant) - PVC is disposable — dashboards and datasources are all config-provisioned ## Deployment and Testing - [ ] No deployment needed — documentation-only change - [ ] `docs-check-links` passes - [ ] `docs-check-index` passes Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/258
2026-02-23 15:06:00 -08:00
## Grafana
Mikado chain for upgrading Grafana to 12.x with kustomize and home-built containers. Track progress with `mise run docs-mikado upgrade-grafana`.
- [[upgrade-grafana]]
- [[kustomize-grafana-deployment]]
- [[build-grafana-container]]
Upgrade k8s forgejo-runner from v6.3.1 to v12.x (#249) ## Summary - C2 Mikado chain for upgrading the k8s forgejo-runner daemon (6 major versions behind) - Root goal card with two leaf prerequisites: workflow validation and config review - Ringtail runner is already at ~v12.6.4 via nixpkgs, no work needed there ## Mikado Chain ``` upgrade-k8s-runner (goal) ├── validate-workflows-against-v12 (leaf) └── review-runner-config-v12 (leaf) ``` Both leaves are actionable now. The biggest risk is workflow schema validation (introduced in v8/v9) rejecting our existing workflows. ## Next Steps Work the leaf nodes in a follow-up session, then attempt the goal. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/249
2026-02-22 17:12:45 -08:00
## Forgejo Runner
Mikado chain for upgrading the k8s forgejo-runner daemon from v6.3.1 to v12.x. Track progress with `mise run docs-mikado upgrade-k8s-runner`.
- [[upgrade-k8s-runner]]
- [[validate-workflows-against-v12]]
- [[review-runner-config-v12]]
Reference in a new issue Copy permalink