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

Add towncrier changelog system (#86)

Browse source 
## Summary
- Configure towncrier with custom types (feature, bugfix, infra, doc, misc)
- Build initial v0.1.0 changelog from zk management log entries
- Integrate towncrier into build-blumeops workflow
- Update README to mark Phase 1b complete

## How It Works
1. Add changelog fragments to `docs/changelog.d/` as `<id>.<type>.md`
2. When running build-blumeops workflow, towncrier collects fragments
3. CHANGELOG.md is updated and fragments are removed
4. Changes are committed back to main before docs build

## Testing
- [x] Tested `uvx towncrier build` locally
- [ ] Test workflow execution (after merge)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/86
This commit is contained in:
Erich Blume 2026-02-03 11:48:13 -08:00
commit 9a8587b83f
6 changed files with 184 additions and 17 deletions
Download patch file Download diff file Expand all files Collapse all files

54
.forgejo/workflows/build-blumeops.yaml
View file

@ -3,8 +3,7 @@
# Creates a versioned release of BlumeOps with all build artifacts.
# Currently includes:
# - Documentation site (Quartz static build)
#
# Future additions may include other release artifacts.
# - Changelog (built from towncrier fragments)
#
# Usage:
# 1. Go to Actions > Build BlumeOps > Run workflow
@ -69,6 +68,57 @@ jobs:
- name: Checkout
uses: actions/checkout@v4
with:
# Need full history for git operations
fetch-depth: 0
- name: Install uv
run: |
curl -LsSf https://astral.sh/uv/install.sh | sh
echo "$HOME/.local/bin" >> "$GITHUB_PATH"
- name: Build changelog
run: |
VERSION="${{ steps.version.outputs.version }}"
# Check if there are any changelog fragments
FRAGMENTS=$(find docs/changelog.d -name "*.md" -not -name ".gitkeep" 2>/dev/null | wc -l)
if [ "$FRAGMENTS" -gt 0 ]; then
echo "Found $FRAGMENTS changelog fragments, building changelog..."
~/.local/bin/uvx towncrier build --version "$VERSION" --yes
echo "changelog_updated=true" >> "$GITHUB_OUTPUT"
else
echo "No changelog fragments found, skipping towncrier"
echo "changelog_updated=false" >> "$GITHUB_OUTPUT"
fi
id: changelog
- name: Commit changelog updates
if: steps.changelog.outputs.changelog_updated == 'true'
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
VERSION="${{ steps.version.outputs.version }}"
# Configure git
git config user.name "Forgejo Actions"
git config user.email "actions@forge.ops.eblu.me"
# Stage changes (CHANGELOG.md updated, fragments removed)
git add docs/CHANGELOG.md docs/changelog.d/
# Commit
git commit -m "Release $VERSION: Update changelog
Built changelog from towncrier fragments.
[skip ci]"
# Push to main
git push origin HEAD:main
echo "Changelog committed and pushed"
- name: Build docs
run: |

16
CLAUDE.md
View file

@ -12,7 +12,7 @@ blumeops is Erich Blume's GitOps repository for personal infrastructure manageme
1. **CRITICAL: Always use `--context=minikube-indri` with kubectl commands.** The user has work contexts configured that must never be touched. Every kubectl command must explicitly specify the context to prevent accidental operations against the wrong cluster.
2. At the start of every session, even if the user asked to do something else, run `mise run zk-docs -- --style=header --color=never --decorations=always` in order to review the `blumeops` documentation. The docs live in `docs/` and are git-managed in this repo. (The user's main zk at `~/code/personal/zk` is separate and synced via obsidian-sync.)
2. At the start of every session, even if the user asked to do something else, run `mise run zk-docs -- --style=header --color=never --decorations=always` to review the blumeops documentation. The docs are hosted at https://docs.ops.eblu.me and source lives in `docs/`. The `docs/zk/` cards are legacy but still useful as reference.
3. When making any changes, start by making sure you're on the `main` git branch and up-to-date, and then create a feature branch. Commit often while working, and create a PR using:
```fish
@ -35,7 +35,15 @@ mise run pr-comments <pr_number>
```
Address each unresolved comment before proceeding. The user will resolve comments on the Forge UI as they are addressed.
4. Always keep the docs (`docs/`) up to date with any changes, and suggest new links to new cards whenever appropriate. Refer back to the docs often during the process of planning and making corrections to ensure accuracy, and if you make a mistake, figure out a way to guard against it using the docs. The docs use Obsidian wiki-link syntax (`[[link]]`).
4. When making changes, add a towncrier changelog fragment. Use the branch name as the identifier when possible, or use orphan (`+`) otherwise:
```bash
# Using branch name (preferred)
echo "Add new feature X" > docs/changelog.d/feature/new-feature.feature.md
# Orphan fragment (when no branch name fits)
echo "Fix bug Y" > docs/changelog.d/+fix-bug-y.bugfix.md
```
Fragment types: `feature`, `bugfix`, `infra`, `doc`, `misc`. Fragments are collected into CHANGELOG.md during releases.
5. Use `Brewfile` and `mise.toml` to install tools needed on the development workstation (typically hostnamed "gilbert", username "eblume").
@ -52,7 +60,9 @@ Address each unresolved comment before proceeding. The user will resolve comment
## Project Structure
```
./docs/ # blumeops documentation (Obsidian wiki-link format)
./docs/ # blumeops documentation (Diataxis structure, built with Quartz)
./docs/changelog.d/ # towncrier changelog fragments
./docs/zk/ # legacy zettelkasten cards (read-only reference)
./mise-tasks/ # management and utility scripts run via `mise run`
./ansible/playbooks/ # ansible playbooks (indri.yml is primary)
./ansible/roles/ # ansible roles for indri-hosted services

60
docs/CHANGELOG.md Normal file
View file

@ -0,0 +1,60 @@
# Changelog
All notable changes to BlumeOps are documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
<!-- towncrier release notes start -->
## [0.1.0] - 2026-02-03
This is a historical release which doesn't actually exist and which aggregates
the changelogs prior to this date. The work on this blumeops project more or
less began around Jan 16 2026. To an extent you can find corroborating details
in the git commit log, but at the beginning (during this initial phase) there
was a fairly large amount of non-source-controlled work. If a more accurate
record is needed for this work, you may find it in borgmatic zk backups from
this time period.
### Features
- Add Grafana Alloy for metrics remote_write to Prometheus
- Add Alloy DaemonSet for automatic pod log collection and service health probes
- Set up Borgmatic daily backups to Sifaka NAS with PostgreSQL streaming support
- Add CloudNativePG PostgreSQL metrics scraping via Tailscale service
- Add devpi PyPI caching proxy in Kubernetes with custom container image
- Add Forgejo Actions CI runner in Kubernetes with host mode execution
- Add Homepage service dashboard with automatic Kubernetes service discovery
- Add Jellyfin media server with VideoToolbox hardware transcoding on indri
- Add Kiwix offline Wikipedia server with kiwix-tools on indri
- Add kube-state-metrics for Kubernetes resource metrics (pods, deployments, etc.)
- Add Loki log aggregation with 31-day retention and Grafana integration
- Add Miniflux RSS/Atom feed reader connected to PostgreSQL
- Add Navidrome music streaming server with NFS storage from Sifaka
- Add Prometheus metrics collection on indri with Sifaka node_exporter scraping
- Add TeslaMate vehicle data logger with 18 Grafana dashboards
- Add Transmission BitTorrent daemon for ZIM archive downloads
- Add Zot OCI registry as pull-through cache for Docker Hub, GHCR, and Quay
### Bug Fixes
- Build Alloy with CGO for macOS native DNS resolver (fixes Tailscale MagicDNS)
- Suppress noisy "v1 Endpoints is deprecated" warning from minikube storage-provisioner
### Infrastructure
- Deploy ArgoCD for GitOps continuous delivery with manual sync policy for workloads
- Set up Caddy reverse proxy for *.ops.eblu.me with ACME DNS-01 TLS via Gandi
- Deploy CloudNativePG operator and blumeops-pg PostgreSQL cluster in Kubernetes
- Migrate Grafana from Homebrew to Kubernetes via Helm chart
- Migrate Kiwix to Kubernetes with torrent-sync sidecar and ZIM watcher CronJob
- Migrate Loki to Kubernetes StatefulSet with 50Gi PVC
- Migrate Miniflux from Homebrew to Kubernetes with CloudNativePG database
- Set up Minikube single-node Kubernetes cluster on indri with Tailscale API access
- Migrate minikube from podman to docker driver for better stability and NFS support
- Manage Prometheus configuration via Ansible
- Migrate Prometheus to Kubernetes StatefulSet with 50Gi PVC
- Set up Pulumi for Tailnet ACL management with OAuth authentication
- Migrate Transmission to Kubernetes with NFS storage from Sifaka
- Migrate Zot registry from Tailscale serve to Caddy reverse proxy at registry.ops.eblu.me
- Integrate Zot as minikube registry mirror for all image pulls

36
docs/README.md
View file

@ -53,17 +53,16 @@ The documentation is being restructured to follow the [Diataxis](https://diataxi
**First release:** [v1.0.0](https://forge.ops.eblu.me/eblume/blumeops/releases/tag/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](https://towncrier.readthedocs.io/) using news fragments from zk cards
- [ ] Add `docs.ops.eblu.me` link to homepage dashboard
### Phase 1b: CD & Hosting (Complete)
- [x] Build and tag `quartz` container (`mise run container-tag-and-release quartz v1.0.0`)
- [x] Create ArgoCD manifests for `docs` deployment
- [x] Add `docs.ops.eblu.me` to Caddy reverse proxy
- [x] Configure deployment with `DOCS_RELEASE_URL`
- [x] Test end-to-end: commit -> build -> release -> deploy
- [x] Set up `CHANGELOG.md` with [towncrier](https://towncrier.readthedocs.io/)
- [x] Add `docs.ops.eblu.me` link to homepage dashboard (via gethomepage.dev annotations)
**Docs URL:** https://docs.ops.eblu.me
### Phase 2: Tutorials
Learning-oriented content for getting started.
@ -112,7 +111,8 @@ Understanding-oriented discussion of concepts and decisions.
```
docs/
├── README.md # This file
├── CHANGELOG.md # Documentation changelog (planned)
├── CHANGELOG.md # Release changelog (built by towncrier)
├── changelog.d/ # Towncrier news fragments
├── tutorials/ # Learning-oriented (planned)
├── how-to/ # Task-oriented (planned)
├── reference/ # Information-oriented (planned)
@ -122,6 +122,18 @@ docs/
└── ... # Service-specific cards and notes
```
## Adding Changelog Entries
When making changes, add a news fragment to `docs/changelog.d/`:
```bash
# 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:

0
docs/changelog.d/.gitkeep Normal file
View file

35
towncrier.toml Normal file
View file

@ -0,0 +1,35 @@
# Towncrier configuration for BlumeOps changelog
# https://towncrier.readthedocs.io/
[tool.towncrier]
directory = "docs/changelog.d"
filename = "docs/CHANGELOG.md"
package = ""
title_format = "## [{version}] - {project_date}"
issue_format = ""
underlines = ["", "", ""]
[[tool.towncrier.type]]
directory = "feature"
name = "Features"
showcontent = true
[[tool.towncrier.type]]
directory = "bugfix"
name = "Bug Fixes"
showcontent = true
[[tool.towncrier.type]]
directory = "infra"
name = "Infrastructure"
showcontent = true
[[tool.towncrier.type]]
directory = "doc"
name = "Documentation"
showcontent = true
[[tool.towncrier.type]]
directory = "misc"
name = "Miscellaneous"
showcontent = false