blumeops/docs/README.md

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 (Current)

• Build and tag quartz container (mise run container-tag-and-release quartz v1.0.0)
• Create ArgoCD manifests for quartz deployment
• Add docs.ops.eblu.me to Caddy reverse proxy
• Configure deployment with DOCS_RELEASE_URL:

  https://forge.ops.eblu.me/eblume/blumeops/releases/download/v1.0.0/docs-v1.0.0.tar.gz
  

• Test end-to-end: commit -> build -> release -> deploy
• Set up CHANGELOG.md with towncrier using news fragments from zk cards
• Add docs.ops.eblu.me link to homepage dashboard

Phase 2: Tutorials

Learning-oriented content for getting started.

• Create tutorials/ directory
• "Getting Started with BlumeOps" - What this is and how to explore it
• "Setting Up a Similar Environment" - For replicators
• "Your First Contribution" - For potential contributors

Phase 3: 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"

Phase 4: Reference

Information-oriented technical descriptions.

• Create reference/ directory
• Service reference pages (migrate from zk cards)
• Infrastructure inventory
• Configuration reference
• API/CLI reference for mise tasks

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)

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
• Mirror docs to GitHub Pages for public access (optional)

Current Directory Layout

docs/
├── README.md          # This file
├── CHANGELOG.md       # Documentation changelog (planned)
├── tutorials/         # Learning-oriented (planned)
├── how-to/            # Task-oriented (planned)
├── reference/         # Information-oriented (planned)
├── explanation/       # Understanding-oriented (planned)
└── zk/                # Zettelkasten cards (temporary)
    ├── 1767747119-YCPO.md  # Main blumeops overview card
    └── ...                  # Service-specific cards and notes

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.