Add Phase 3 tutorials with audience targeting #94

Merged
eblume merged 2 commits from feature/phase3-tutorials into main 2026-02-03 18:51:58 -08:00
Owner

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

  • 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

## 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)
Create tutorials directory with learning-oriented content:
- what-is-blumeops: High-level orientation (Reader, AI)
- exploring-the-docs: Navigation guide (All audiences)
- ai-assistance-guide: Context for AI assistance (AI, Owner)
- contributing: First contribution workflow (Contributor)
- replicating-blumeops: Overview for replicators

Add replication sub-tutorials:
- tailscale-setup: Networking foundation
- kubernetes-bootstrap: Cluster setup
- argocd-config: GitOps configuration
- observability-stack: Metrics, logs, dashboards

Each tutorial explicitly identifies target audiences and links
heavily to reference material rather than re-explaining.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ -0,0 +76,4 @@
2. Preview with `argocd app diff <service>`
3. Deploy with `argocd app sync <service>`
### Indri Service Changes
Author
Owner

instead of these sections, make a "Mise Tasks" section and include a table detailing each mise task and when to use it. And by the way, skip the --check --diff pass on provision-indri, I want to skip that going forward, I'll remove it from CLAUDE.md soon

instead of these sections, make a "Mise Tasks" section and include a table detailing each mise task and when to use it. And by the way, skip the --check --diff pass on provision-indri, I want to skip that going forward, I'll remove it from CLAUDE.md soon
@ -0,0 +38,4 @@
git clone ssh://git@forge.ops.eblu.me:2222/eblume/blumeops.git
cd blumeops
git checkout -b feature/your-change-name
```
Author
Owner

somewhere around here, include notes on installing homebrew, using Brewfile to install tools such as tea and mise (check that mise is in the brewfile please), and using mise to install language toolchains. Figure out how precommit is orchestrated here (I think it's in mise) and include that detail as well, with the result being that the dev should be able to run pre-commit now and have it pass on a fresh clone.

somewhere around here, include notes on installing homebrew, using Brewfile to install tools such as tea and mise (check that mise is in the brewfile please), and using mise to install language toolchains. Figure out how precommit is orchestrated here (I think it's in mise) and include that detail as well, with the result being that the dev should be able to run pre-commit now and have it pass on a fresh clone.
@ -0,0 +77,4 @@
For Kubernetes changes:
```bash
# Preview what will change
argocd app diff <service>
Author
Owner

the dev will need to set target revisions for their app, and for the app-of-apps if it's a new app.

the dev will need to set target revisions for their app, and for the app-of-apps if it's a new app.
@ -0,0 +84,4 @@
```bash
# Dry run
mise run provision-indri -- --check --diff --tags <role>
```
Author
Owner

Include pulumi preview for DNS changes here. There's a mise task for it.

Include pulumi preview for DNS changes here. There's a mise task for it.
@ -0,0 +114,4 @@
Erich will review your PR and may leave comments. Check for feedback:
```bash
mise run pr-comments <pr_number>
Author
Owner

this is intended for AI, skip it in this tutorial.

this is intended for AI, skip it in this tutorial.
@ -0,0 +140,4 @@
## Getting Help
- Browse [[reference/index|Reference]] for technical details
- Check `CLAUDE.md` in the repo for rules and conventions
Author
Owner

nope, ai only

nope, ai only
@ -0,0 +5,4 @@
- getting-started
---
# Exploring the Documentation
Author
Owner

let's update the root index.md to link directly to this tutorial, it's a great entry point for people fresh to the docs

let's update the root index.md to link directly to this tutorial, it's a great entry point for people fresh to the docs
@ -0,0 +19,4 @@
|---------|---------|-------------|
| **[[tutorials/index | Tutorials]]** | Learning-oriented | "I'm new and want to understand" |
| **[[reference/index | Reference]]** | Information-oriented | "I need specific technical details" |
| **How-to** (planned) | Task-oriented | "I need to do X" |
Author
Owner

please update docs/README.md phase plans to include a note to return to this tutorial with updates

please update docs/README.md phase plans to include a note to return to this tutorial with updates
@ -0,0 +50,4 @@
Getting started with changes:
- [[contributing]] walks through the workflow
- [[reference/index|Reference]] tells you where things live
- The `CLAUDE.md` in the repo root has contribution rules
Author
Owner

nope, only for ai

nope, only for ai
@ -0,0 +52,4 @@
- [[reference/index|Reference]] tells you where things live
- The `CLAUDE.md` in the repo root has contribution rules
### For Replicators
Author
Owner

Include like a sentence here explaining what a replicator is in this context

Include like a sentence here explaining what a replicator is in this context
@ -0,0 +64,4 @@
Documentation uses `[[wiki-links]]` for cross-references:
- `[[service-name]]` links to a reference page
- `[[folder/page]]` links to nested pages
- `[[page|Display Text]]` customizes the link text
Author
Owner

Include a note here that pre-commit will automatically check that links are correct and unambiguous.

Include a note here that pre-commit will automatically check that links are correct and unambiguous.
@ -0,0 +26,4 @@
| Component | BlumeOps Uses | Minimum Alternative |
|-----------|---------------|---------------------|
| **Server** | Mac Mini M1 | Any machine with 16GB RAM |
Author
Owner

honestly you dont even need that although I wouldn't recommend less. Maybe just "sufficient RAM (16GB recommended)"

honestly you dont even need that although I wouldn't recommend less. Maybe just "sufficient RAM (16GB recommended)"
@ -0,0 +45,4 @@
This replaces: traditional VPNs, port forwarding, dynamic DNS
### Phase 2: Kubernetes Cluster
Author
Owner

I think there needs to be a phase prior to this with its own tutorial, "core services", which should be where forgejo and zot are configured, although zot is technically optional. I mean forgejo is also optional but it's really a central idea: forgejo is the tool we use to bootstrap the gitops. I'm going to guess forgejo gets discussed later in this or other tutorials, so that'll need to be moved around.

I think there needs to be a phase prior to this with its own tutorial, "core services", which should be where forgejo and zot are configured, although zot is technically optional. I mean forgejo is also optional but it's really a central idea: forgejo is the tool we use to bootstrap the gitops. I'm going to guess forgejo gets discussed later in this or other tutorials, so that'll need to be moved around.
@ -0,0 +80,4 @@
Without observability, you're flying blind.
### Phase 5: Your First Services
Author
Owner

We should include quartz docs in this list. Do we have a service card for docs? We should add one if not.

We should include quartz docs in this list. Do we have a service card for docs? We should add one if not.
@ -0,0 +46,4 @@
For Tailscale access:
```bash
tailscale serve --bg --https 8443 https+insecure://localhost:$(kubectl -n argocd get svc argocd-server -o jsonpath='{.spec.ports[?(@.name=="https")].port}')
Author
Owner

mmm nope there is an ansible role for this. Oh wow come to think of it we might not have any reference material for ansible roles yet! Start a section for it and link to it here.

mmm nope there is an ansible role for this. Oh wow come to think of it we might not have any reference material for ansible roles yet! Start a section for it and link to it here.
@ -0,0 +49,4 @@
tailscale serve --bg --https 8443 https+insecure://localhost:$(kubectl -n argocd get svc argocd-server -o jsonpath='{.spec.ports[?(@.name=="https")].port}')
```
Or create a Tailscale Ingress in Kubernetes.
Author
Owner

ah, there needs to be a reference card for the tailscale k8s operator as well, and link to it from reference/kubernetes/apps (and here).

ah, there needs to be a reference card for the tailscale k8s operator as well, and link to it from reference/kubernetes/apps (and here).
@ -0,0 +56,4 @@
### Install the CLI
```bash
brew install argocd # macOS
Author
Owner

actually maybe just refer to the fact that blumeops contains a Brewfile with argocd, or they can install it any other way

actually maybe just refer to the fact that blumeops contains a Brewfile with argocd, or they can install it any other way
@ -0,0 +131,4 @@
Expose via Tailscale:
```bash
kubectl -n monitoring port-forward svc/grafana 3000:80 &
tailscale serve --bg --https 3000 http://localhost:3000
Author
Owner

ansible role

ansible role
@ -0,0 +1,67 @@
---
title: what-is-blumeops
Author
Owner

Actually this entire tutorial should be a an Explanation instead. Remove it. Replace it with a tutorial on how to add an argocd-managed service, including all the important steps like setting up the ingress and the homepage annotations and grafana dashboards, etc.

Actually this entire tutorial should be a an Explanation instead. Remove it. Replace it with a tutorial on how to add an argocd-managed service, including all the important steps like setting up the ingress and the homepage annotations and grafana dashboards, etc.
Tutorial changes:
- Replace what-is-blumeops with adding-a-service tutorial
- Update ai-assistance-guide with Mise Tasks table
- Update contributing with tooling setup, target revisions, DNS preview
- Remove AI-only sections from contributing and exploring-the-docs
- Add replicator explanation to exploring-the-docs
- Add pre-commit link validation note
- Add Core Services phase to replication roadmap
- Add docs service to services list in replicating-blumeops

New reference cards:
- docs.md - Quartz documentation service
- tailscale-operator.md - Kubernetes ingress operator
- ansible/roles.md - Available ansible roles

Other updates:
- Add mise to Brewfile
- Update docs/index.md to link to exploring-the-docs
- Add notes to update exploring-the-docs in future phases
- Link tailscale-operator from apps.md

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
eblume merged commit 7ebac4aef6 into main 2026-02-03 18:51:58 -08:00
Sign in to join this conversation.
No reviewers
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
eblume/blumeops!94
No description provided.