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

48 lines
2 KiB
Markdown
Raw Permalink Normal View History

Move zk cards to docs/zk/ for documentation restructuring (#84) ## Summary - Move all existing zettelkasten cards from `docs/` to `docs/zk/` as a temporary holding area - Update `zk-docs` mise task to look in the new location - Add `docs/README.md` explaining the Diataxis-based restructuring plan and target audiences ## Context This is phase 1 of a multi-phase documentation restructuring effort. The goal is to reorganize docs to follow the Diataxis framework while serving multiple audiences: 1. Erich (owner) - knowledge graph/zk 2. Claude/AI agents - memory and context enrichment 3. New external readers - high-level overview 4. Potential operators/contributors - onboarding 5. Replicators - people wanting to duplicate the approach ## Testing - [x] Verified `mise run zk-docs` still works with the new path - [x] Updated obsidian.nvim config (in ~/.config/nvim) to point to new path ## Note The obsidian.nvim config change is outside this repo but was made as part of this work. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/84
2026-02-03 09:13:50 -08:00
---
Remove title slug check and test duplicate titles (#116) ## Summary - Remove `docs-check-titles` pre-commit hook and mise task — wiki-links resolve by filename stem, not frontmatter title, so slug-format titles and uniqueness aren't needed - Add two test cards (`title-test-alpha`, `title-test-beta`) with identical `title: Title Test Card` to verify duplicate titles don't break Quartz or obsidian.nvim - Retitle `index.md` from `blumeops-documentation` to `BlumeOps` - Add GitHub and Forgejo repo links to homepage intro ## Test plan - [ ] Deploy to docs site and verify both test cards render and cross-link correctly - [ ] Verify homepage title renders as "BlumeOps" - [ ] Verify repo links on homepage work - [ ] After confirming, remove test cards in a follow-up 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/116
2026-02-07 21:26:18 -08:00
title: BlumeOps
C0: doc review — index.md, add ringtail to infra overview Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-06 06:14:40 -07:00
modified: 2026-05-06
last-reviewed: 2026-05-06
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
aliases: []
id: index
tags: []
Move zk cards to docs/zk/ for documentation restructuring (#84) ## Summary - Move all existing zettelkasten cards from `docs/` to `docs/zk/` as a temporary holding area - Update `zk-docs` mise task to look in the new location - Add `docs/README.md` explaining the Diataxis-based restructuring plan and target audiences ## Context This is phase 1 of a multi-phase documentation restructuring effort. The goal is to reorganize docs to follow the Diataxis framework while serving multiple audiences: 1. Erich (owner) - knowledge graph/zk 2. Claude/AI agents - memory and context enrichment 3. New external readers - high-level overview 4. Potential operators/contributors - onboarding 5. Replicators - people wanting to duplicate the approach ## Testing - [x] Verified `mise run zk-docs` still works with the new path - [x] Updated obsidian.nvim config (in ~/.config/nvim) to point to new path ## Note The obsidian.nvim config change is outside this repo but was made as part of this work. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/84
2026-02-03 09:13:50 -08:00
---
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
Welcome to the BlumeOps (aka "Blue Mops") documentation. Here you will find
hopefully everything you'll need to understand and operate my personal digital
infrastructure.
Move zk cards to docs/zk/ for documentation restructuring (#84) ## Summary - Move all existing zettelkasten cards from `docs/` to `docs/zk/` as a temporary holding area - Update `zk-docs` mise task to look in the new location - Add `docs/README.md` explaining the Diataxis-based restructuring plan and target audiences ## Context This is phase 1 of a multi-phase documentation restructuring effort. The goal is to reorganize docs to follow the Diataxis framework while serving multiple audiences: 1. Erich (owner) - knowledge graph/zk 2. Claude/AI agents - memory and context enrichment 3. New external readers - high-level overview 4. Potential operators/contributors - onboarding 5. Replicators - people wanting to duplicate the approach ## Testing - [x] Verified `mise run zk-docs` still works with the new path - [x] Updated obsidian.nvim config (in ~/.config/nvim) to point to new path ## Note The obsidian.nvim config change is outside this repo but was made as part of this work. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/84
2026-02-03 09:13:50 -08:00
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
**New here?** Start with [[exploring-the-docs]] to find your way around.
Link reference section from docs index Add navigation to Reference section and clarify that README is temporary home during Diataxis restructuring. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-02-03 14:32:59 -08:00
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
## What is BlumeOps?
BlumeOps is my personal homelab infrastructure managed entirely through code.
Remove title slug check and test duplicate titles (#116) ## Summary - Remove `docs-check-titles` pre-commit hook and mise task — wiki-links resolve by filename stem, not frontmatter title, so slug-format titles and uniqueness aren't needed - Add two test cards (`title-test-alpha`, `title-test-beta`) with identical `title: Title Test Card` to verify duplicate titles don't break Quartz or obsidian.nvim - Retitle `index.md` from `blumeops-documentation` to `BlumeOps` - Add GitHub and Forgejo repo links to homepage intro ## Test plan - [ ] Deploy to docs site and verify both test cards render and cross-link correctly - [ ] Verify homepage title renders as "BlumeOps" - [ ] Verify repo links on homepage work - [ ] After confirming, remove test cards in a follow-up 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/116
2026-02-07 21:26:18 -08:00
Everything lives in a [single git repository](https://github.com/eblume/blumeops), from service configs to
Expose Forgejo publicly at forge.eblu.me (#278) ## Summary Expose Forgejo publicly at `forge.eblu.me` via the Fly.io reverse proxy — the first dynamic, authenticated public-facing service. - **Forgejo hardening:** Domain changed to forge.eblu.me, SSH stays on forge.ops.eblu.me, reverse proxy trust headers configured, local registration locked to external-only (Authentik SSO) - **Tailscale Ingress:** ExternalName Service + Ingress in tailscale-operator creates forge.tail8d86e.ts.net endpoint - **Fly.io proxy:** nginx server block with rate-limited auth endpoints (3r/s), fail2ban with custom nginx-deny action, security headers, /swagger blocked, WebSocket support, 512m body limit - **Authentik:** OAuth callback updated to forge.eblu.me - **DNS/TLS:** CNAME record in Pulumi, cert in fly-setup - **Rename:** ~29 files updated from forge.ops.eblu.me to forge.eblu.me (HTTPS refs only; SSH, container builds, and Caddy table kept as-is) ## Deployment Order 1. `mise run provision-indri -- --tags forgejo` (config changes) 2. Verify forge.ops.eblu.me still works 3. `argocd app set tailscale-operator --revision feature/forge-public && argocd app sync tailscale-operator` 4. Verify `curl https://forge.tail8d86e.ts.net` 5. `cd fly && fly deploy` 6. Verify pre-DNS: `curl -H "Host: forge.eblu.me" https://blumeops-proxy.fly.dev/` 7. `fly certs add forge.eblu.me -a blumeops-proxy` 8. `argocd app set authentik --revision feature/forge-public && argocd app sync authentik` 9. `mise run dns-preview && mise run dns-up` 10. Full verification (see below) 11. Rehearse `mise run fly-shutoff` 12. After merge: reset ArgoCD revisions to main, re-sync ## Verification Checklist - [ ] forge.eblu.me loads, shows public repos - [ ] forge.ops.eblu.me still works from tailnet - [ ] SSH clone via forge.ops.eblu.me:2222 works - [ ] HTTPS clone via forge.eblu.me works - [ ] UI shows forge.eblu.me for HTTPS clone, forge.ops.eblu.me for SSH - [ ] /swagger returns 403 - [ ] Rapid login attempts trigger 429 rate limit - [ ] fail2ban bans after 5 failed logins in 10 minutes - [ ] ArgoCD can still sync (SSH unaffected) - [ ] `mise run fly-shutoff` stops all public traffic - [ ] `mise run services-check` passes Reviewed-on: https://forge.eblu.me/eblume/blumeops/pulls/278
2026-03-03 08:40:41 -08:00
deployment automation. Even the [[forgejo]] instance that [hosts this repo](https://forge.eblu.me/eblume/blumeops)
Remove title slug check and test duplicate titles (#116) ## Summary - Remove `docs-check-titles` pre-commit hook and mise task — wiki-links resolve by filename stem, not frontmatter title, so slug-format titles and uniqueness aren't needed - Add two test cards (`title-test-alpha`, `title-test-beta`) with identical `title: Title Test Card` to verify duplicate titles don't break Quartz or obsidian.nvim - Retitle `index.md` from `blumeops-documentation` to `BlumeOps` - Add GitHub and Forgejo repo links to homepage intro ## Test plan - [ ] Deploy to docs site and verify both test cards render and cross-link correctly - [ ] Verify homepage title renders as "BlumeOps" - [ ] Verify repo links on homepage work - [ ] After confirming, remove test cards in a follow-up 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/116
2026-02-07 21:26:18 -08:00
is defined within it, making BlumeOps fully self-hosting. It's a digital life
raft I built for myself as I went, and you can see it all from within your
editor of choice. (I recommend vim.)
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
These services run on my home [[hosts|infrastructure]], primarily an m1 mac
C0: doc review — index.md, add ringtail to infra overview Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-06 06:14:40 -07:00
mini named [[indri]], a NixOS GPU host called [[ringtail]] running a k3s
cluster, and a Synology NAS called [[sifaka]]. The infrastructure is networked
via [[tailscale]], with the domain `eblu.me` hosted via [[gandi]],
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
[[caddy]] providing a private reverse proxy for tailnet devices, and
[[flyio-proxy|Fly.io]] serving public-facing services like
[this documentation site](https://docs.eblu.me).
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
The goal of BlumeOps is threefold:
1. To provide a rich array of useful personal services in order to manage my
own digital life.
2. To exercise my skills as a software engineer specializing in
Platforms/DevOps/SRE.
3. To act as a portfolio piece for talking about building hosted software
platforms.
Link reference section from docs index Add navigation to Reference section and clarify that README is temporary home during Diataxis restructuring. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-02-03 14:32:59 -08:00
## Sections
Fix spider trap: disable SPA mode, remove index files, relax wiki-links (#290) ## Summary Fixes the Facebook crawler spider trap that's been generating infinite recursive URLs like `/how-to/tutorials/tutorials/how-to/explanation/...` for several days. **Root cause:** Quartz SPA mode + nginx `try_files` fallback to `index.html` meant any fabricated URL returned the root HTML shell with HTTP 200. Crawlers followed relative links from those fake URLs, creating infinite recursion. **Fix:** - Disable Quartz SPA mode (`enableSPA: false`) — all pages are now fully static HTML - Replace nginx SPA fallback with `=404` + Quartz's static `404.html` - Remove `robots.txt` exclusions (no longer needed) **Docs cleanup (Obsidian.nvim compat no longer needed):** - Delete hand-curated category index files (`tutorials.md`, `reference.md`, `how-to.md`, `explanation.md`) — Quartz auto-generates folder pages - Delete `postgresql-storage.md` (redirect stub) and `migrate-forgejo-from-brew.md` (stale history) - Drop `docs-check-index` and `docs-check-filenames` prek hooks - Rewrite `docs-check-links` to allow path-based wiki-links (`[[path/to/file]]`) and only error on true ambiguity - Add `ai-docs` doc tree listing to replace index files for AI context - Add natural cross-links from reference cards to fix orphan docs ## Deployment and Testing - [ ] Merge and let the build pipeline run - [ ] Verify docs.eblu.me serves pages correctly with full page loads - [ ] Verify non-existent URLs return 404 - [ ] Monitor crawler traffic — should drop to near zero for fabricated URLs Reviewed-on: https://forge.eblu.me/eblume/blumeops/pulls/290
2026-03-09 11:59:43 -07:00
- [Tutorials](/tutorials/) - Learning-oriented guides for getting started
- [Reference](/reference/) - Technical specifications and service details
- [How-to](/how-to/) - Task-oriented instructions for common operations
- [Explanation](/explanation/) - Understanding the "why" behind BlumeOps
Improve build workflow with version bump selection and changelog in releases (#104) ## Summary - Add `version_type` choice input with options: BUMP_PATCH (default), BUMP_MINOR, BUMP_MAJOR, SPECIFIC_VERSION - Add optional `specific_version` input for explicit version selection - Include changelog content in Forgejo release body under "What's Changed" section - Move CHANGELOG.md to repository root (still copied into docs during Quartz build) - Add CHANGELOG link to docs index page - Update doc-links script to recognize build-time docs from repo root ## Changes **Workflow inputs:** - Previously: single optional `version` string input - Now: `version_type` choice dropdown (defaults to BUMP_PATCH) + optional `specific_version` for explicit versions **Release body:** - Previously: just asset download instructions - Now: includes "What's Changed" section with changelog entries for this release **CHANGELOG.md location:** - Previously: `docs/CHANGELOG.md` - Now: `CHANGELOG.md` (repo root), copied into docs content during build ## Deployment and Testing - [ ] Run build workflow with BUMP_PATCH (default) - [ ] Run build workflow with BUMP_MINOR - [ ] Verify changelog appears in release body - [ ] Verify docs site includes CHANGELOG page Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/104
2026-02-04 08:13:16 -08:00
- [[CHANGELOG]] - Release history and changes
Reference in a new issue Copy permalink