Erich Blume 517080aeab Add reference/tools/ category with Dagger, ArgoCD CLI, Ansible, and Pulumi cards (#178 )

## Summary

- Create `docs/reference/tools/` with four reference cards: Dagger (build engine), ArgoCD CLI (deployment workflows), Ansible (config management), and Pulumi (DNS/Tailscale IaC)
- Move `ansible/roles.md` → `tools/ansible.md`, broadened with CLI patterns and dry-run usage
- Update `reference.md` index: add "Tools" section, remove old "Ansible" section
- Update `update-documentation.md` to reflect Dagger build process (workflow steps, manual build recipe, runner environment)
- Update `adopt-dagger-ci.md` plan to note how-to articles were handled via reference card + existing how-to updates
- Fix all broken `[[roles]]` wiki-links across 5 files → `[[ansible]]`

## Verification

- `docs-check-links` ✓ — no broken wiki-links
- `docs-check-index` ✓ — all docs referenced in category index
- `docs-check-filenames` ✓ — no duplicate filenames
- All pre-commit hooks pass

Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/178

2026-02-12 19:18:46 -08:00

2.4 KiB

Raw Blame History

title

modified

Dagger

Build engine for BlumeOps CI/CD pipelines. Replaces shell-based build scripts with Python functions that run identically locally and in CI.

Quick Reference

Property	Value
Module	`blumeops-ci`
Engine Version	v0.19.11
SDK	Python
Source	`.dagger/src/blumeops_ci/main.py`
Config	`dagger.json`

Functions

Function	Signature	Description
`build`	`(src, container_name) → Container`	Build a container from `containers/<name>/Dockerfile`
`publish`	`(src, container_name, version, registry?) → str`	Build and push to registry (default: `registry.ops.eblu.me`)
`build_changelog`	`(src, version) → Directory`	Run towncrier to collect changelog fragments
`build_docs`	`(src, version) → File`	Build changelog then Quartz site, return docs tarball

CLI Examples

# Build a container
dagger call build --src=. --container-name=devpi

# Drop into container shell for inspection
dagger call build --src=. --container-name=devpi terminal

# Debug a failure interactively
dagger call --interactive build --src=. --container-name=devpi

# Publish a container to zot
dagger call publish --src=. --container-name=devpi --version=v1.1.0

# Build docs tarball locally
dagger call build-docs --src=. --version=dev export --path=./docs-dev.tar.gz

# Debug a docs build failure
dagger call --interactive build-docs --src=. --version=dev

Secrets

Dagger has a first-class Secret type — values are never logged or cached. Pass secrets from environment variables using the env:VAR syntax:

dagger call release-docs \
  --src=. --version=v1.6.0 \
  --forgejo-token=env:FORGEJO_TOKEN \
  --argocd-token=env:ARGOCD_TOKEN

In forgejo Actions, secrets are injected as env vars. Locally, mise tasks call op read to populate them.

Caveats

Pre-1.0 API — Current version is v0.19.x. Pin the CLI version and test upgrades on a branch before adopting.
Privileged container — The Dagger engine requires privileged container access. The Forgejo runner's DinD sidecar provides this.

forgejo — CI/CD trigger layer
zot — Container registry (publish target)
docs — Documentation site (build target)
adopt-dagger-ci — Adoption plan (phases 1–3 complete)

2.4 KiB Raw Blame History Unescape Escape