blumeops/docs

title
readme

BlumeOps Documentation

Note on naming: The project is properly stylized as BlumeOps, though "blumeops" and "Blue Mops" are also commonly used interchangeably.

This directory contains documentation for BlumeOps, Erich Blume's personal infrastructure GitOps repository.

Documentation Restructuring (In Progress)

The documentation is being restructured to follow the Diataxis documentation framework while serving multiple audiences.

Target Audiences

1. Erich (owner) - A knowledge graph/zettelkasten for quickly recalling important facts about BlumeOps infrastructure and operations.

2. Claude/AI agents - Memory and context enrichment for AI-assisted operations and development.

3. New external readers - People who want to understand "what is BlumeOps?" at a high level.

4. Potential operators/contributors - External readers who want to help operate, modify, or answer questions about BlumeOps, or onboard as a member.

5. Replicators - People who want to duplicate this approach for their own personal infrastructure operations.

Requirements

• Source format: Markdown with optional YAML frontmatter
• Editing: Compatible with Obsidian and obsidian.nvim
• Cross-references: Wiki-link syntax ([[link]]) for internal links
• Output formats: HTML (for web hosting) and PDF (for offline reference)
• Changelog: Track significant documentation changes

Tooling

Selected: Quartz - A TypeScript-based static site generator designed for Obsidian vaults. Features wiki-link support, backlinks, graph view, and excellent Obsidian compatibility.

Architecture:

• Source: Markdown files in docs/ with optional YAML frontmatter
• Build: Quartz builds static HTML/CSS/JS via Forgejo workflow
• Release: Built assets published as Forgejo release attachments
• Hosting: quartz container downloads release bundle on startup and serves via nginx
• URL: docs.ops.eblu.me (planned)

Restructuring Phases

Phase 1a: Foundation & CI (Complete)

• Move existing zk cards to docs/zk/
• Update zk-docs mise task for new path
• Create this README with restructuring plan
• Select documentation tooling (Quartz)
• Create Quartz configuration (quartz.config.ts, quartz.layout.ts)
• Create quartz container for serving static sites
• Create build-blumeops workflow for building releases
• Test the build workflow and verify release creation (v1.0.0)

First release: v1.0.0

Phase 1b: CD & Hosting (Complete)

• Build and tag quartz container (mise run container-tag-and-release quartz v1.0.0)
• Create ArgoCD manifests for docs deployment
• Add docs.ops.eblu.me to Caddy reverse proxy
• Configure deployment with DOCS_RELEASE_URL
• Test end-to-end: commit -> build -> release -> deploy
• Set up CHANGELOG.md with towncrier
• Add docs.ops.eblu.me link to homepage dashboard (via gethomepage.dev annotations)

Docs URL: https://docs.ops.eblu.me

Phase 2: Reference (Complete)

Information-oriented technical descriptions. Built first so other docs can link to reference material.

• Create reference/ directory with index
• Service reference pages (16 services: alloy, argocd, borgmatic, 1password, forgejo, grafana, jellyfin, kiwix, loki, miniflux, navidrome, postgresql, prometheus, teslamate, transmission, zot)
• Infrastructure inventory (hosts, tailscale, routing)
• Kubernetes reference (cluster, apps)
• Storage reference (sifaka, backups)

Reference URL: https://docs.ops.eblu.me/reference/

Phase 3: Tutorials (Complete)

Learning-oriented content for getting started. Each tutorial explicitly identifies its target audiences.

• Create tutorials/ directory with index
• "Exploring the Docs" - How to navigate documentation (All)
• "AI Assistance Guide" - Context for AI-assisted operations (AI, Owner)
• "Contributing" - Your first contribution (Contributor)
• "Adding a Service" - Deploy a new ArgoCD service (Contributor, Replicator)
• "Replicating BlumeOps" - Overview for building similar setup (Replicator)
• Replication sub-tutorials:
  • Tailscale Setup
  • Core Services (Forgejo, Zot)
  • Kubernetes Bootstrap
  • ArgoCD Config
  • Observability Stack
• New reference cards: docs service, tailscale-operator, ansible/roles

Tutorials URL: https://docs.ops.eblu.me/tutorials/

Phase 4: How-to Guides

Task-oriented instructions for specific operations.

• Create how-to/ directory
• Migrate operational content from zk cards
• "How to deploy a new Kubernetes service"
• "How to add a new Ansible role"
• "How to update Tailscale ACLs"
• "How to troubleshoot common issues"
• Update exploring-the-docs with How-to section

Phase 5: Explanation

Understanding-oriented discussion of concepts and decisions.

• Create explanation/ directory
• "Why GitOps?" - Philosophy and approach
• "Architecture Overview" - How everything fits together
• "Security Model" - Tailscale, secrets management, etc.
• "Decision Log" - ADRs (Architecture Decision Records)
• Update exploring-the-docs with Explanation section

Phase 6: Integration & Cleanup

• Migrate remaining useful content from docs/zk/
• Decide fate of zk cards (archive, delete, or keep as separate knowledge base)
• Update CLAUDE.md to reference new doc structure
• Final review of exploring-the-docs for completeness
• Mirror docs to GitHub Pages for public access (optional)

Current Directory Layout

docs/
├── README.md          # This file
├── CHANGELOG.md       # Release changelog (built by towncrier)
├── changelog.d/       # Towncrier news fragments
├── reference/         # Information-oriented (Phase 2)
├── tutorials/         # Learning-oriented (Phase 3)
├── how-to/            # Task-oriented (Phase 4)
├── explanation/       # Understanding-oriented (Phase 5)
└── zk/                # Zettelkasten cards (temporary)
    ├── 1767747119-YCPO.md  # Main blumeops overview card
    └── ...                  # Service-specific cards and notes

Why Reference first? Reference docs are built before tutorials and how-to guides so that learning and task-oriented content can link to authoritative technical descriptions using wiki-links ([[reference/service-name]]).

Adding Changelog Entries

When making changes, add a news fragment to docs/changelog.d/:

# Format: <identifier>.<type>.md
# Types: feature, bugfix, infra, doc, misc
echo "Add new feature X" > docs/changelog.d/20260203-feature-x.feature.md

Fragments are automatically collected into CHANGELOG.md when a release is built.

Viewing the ZK Cards

To view all BlumeOps zettelkasten cards:

mise run zk-docs

This displays all cards tagged with blumeops, starting with the main overview card.