blumeops/docs/how-to/how-to.md

---
title: How-To
tags:
  - how-to
---

# How-To Guides

Task-oriented instructions for common BlumeOps operations. These guides assume you already understand the basic concepts - see [[tutorials|Tutorials]] if you're learning.

## 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 |

## Configuration

| Guide | Description |
|-------|-------------|
| [[update-tailscale-acls]] | Update Tailscale access control policies |
| [[gandi-operations]] | Manage DNS records and cycle the Gandi API token |
| [[use-pypi-proxy]] | Configure pip and publish packages to devpi |
| [[expose-service-publicly]] | Expose a service to the public internet via Fly.io + Tailscale |

## Documentation

| Guide | Description |
|-------|-------------|
| [[update-documentation]] | Publish docs via build-blumeops workflow |

## Knowledge Base

| Guide | Description |
|-------|-------------|
| [[review-documentation]] | Periodically review and maintain documentation |

## Operations

| Guide | Description |
|-------|-------------|
| [[restart-indri]] | Safely shut down and restart indri |
| [[manage-flyio-proxy]] | Deploy, shutoff, and troubleshoot the public proxy |
| [[restore-1password-backup]] | Recover 1Password credentials from borgmatic backup |
| [[troubleshooting]] | Diagnose and fix common issues |

## Plans

Migration and transition plans for upcoming infrastructure changes.

| Plan | Description |
|------|-------------|
| [[plans]] | Index of all plans |
| [[migrate-forgejo-from-brew]] | Transition Forgejo from Homebrew to source-built binary |
| [[add-unifi-pulumi-stack]] | Add Pulumi IaC for UniFi Express 7 |
| [[adopt-dagger-ci]] | Adopt Dagger as CI/CD build engine |
| [[upstream-fork-strategy]] | Stacked-branch forking strategy for upstream projects |
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`
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 \|`

			`## 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 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
			`## Documentation`

			`\| Guide \| Description \|`
			`\|-------\|-------------\|`
			`\| [[update-documentation]] \| Publish docs via build-blumeops workflow \|`

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 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 \|`
			`\|-------\|-------------\|`
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 \|`
			`\| [[migrate-forgejo-from-brew]] \| Transition Forgejo from Homebrew to source-built binary \|`
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			`\| [[add-unifi-pulumi-stack]] \| Add Pulumi IaC 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 \|`