eblume/blumeops
1
1
Fork 0
Code Issues Pull requests Projects Releases 83 Packages Wiki Activity Actions
blumeops/docs/tutorials/replication/core-services.md
Erich Blume b197bd5f58 Adopt Dagger CI for docs build (Phase 2) (#157) 
## Summary

Migrates the docs build pipeline to Dagger (Phase 2 of the Dagger CI adoption plan).

- **Backfill `date-modified` frontmatter** on all 80 docs — Dagger's `--src=.` excludes `.git`, so Quartz can't use git history for page dates. Frontmatter dates work with or without git.
- **New `docs-check-frontmatter` mise task + pre-commit hook** — validates all docs have `title`, `tags`, and `date-modified`
- **New Dagger functions** — `build_changelog` (towncrier in Python container) and `build_docs` (chains changelog → Quartz build in Node container, returns tarball)
- **Simplified CI workflow** — the ~44-line inline Quartz build (clone, npm ci, build, tar, cleanup) is replaced by `dagger call build-docs`. Changelog step remains local on the runner since towncrier needs to modify the host working tree for the git commit.

### Design decisions

- **Towncrier runs twice in CI**: once inside Dagger (for the docs tarball) and once on the runner (for the git commit). This is intentional — Dagger's directory export is additive and can't delete the consumed changelog fragments from the host.
- **Artifact hosting stays on Forgejo Releases** (not migrated to Forgejo Packages as the plan doc originally suggested). That migration can happen independently.
- **`date-modified` frontmatter** preserved even though `build_changelog` installs git — the git there is only for towncrier's `git add` call, not for history. The local iteration story (`dagger call build-docs --src=. --version=dev` with uncommitted changes) depends on frontmatter dates.

### Local iteration

```bash
dagger call build-docs --src=. --version=dev export --path=./docs-dev.tar.gz
tar tf docs-dev.tar.gz | head -20
```

## Deployment and Testing

- [x] `dagger call build-docs --src=. --version=dev` produces valid 1.1MB tarball (149 HTML pages)
- [x] Pre-commit hooks pass (including new `docs-check-frontmatter`)
- [ ] Full `workflow_dispatch` run after merge

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

Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/157
2026-02-11 16:33:16 -08:00

3.3 KiB
Raw Blame History

title date-modified tags
Core Services 2026-02-07
tutorials
replication
forgejo

Core Services Setup

Audiences: Replicator

Prerequisites: tailscale-setup

This tutorial walks through setting up the foundational services that your GitOps infrastructure depends on: a git forge and optionally a container registry.

Why Core Services First?

Before Kubernetes and ArgoCD, you need somewhere to store your infrastructure definitions. forgejo provides:

  • Git hosting for your GitOps repository
  • CI/CD workflows for building and deploying
  • A web interface for code review and PRs

The zot container registry is optional but useful for hosting your own container images.

Step 1: Install Forgejo

Forgejo runs directly on your server (not in Kubernetes) because Kubernetes depends on it.

Using Ansible (BlumeOps Approach)

BlumeOps manages Forgejo via an Ansible role. See roles.

Manual Installation

  1. Download Forgejo from forgejo.org
  2. Create a service user and directories
  3. Configure with app.ini
  4. Set up as a system service

Key configuration points:

  • SSH on a non-standard port (e.g., 2222) to avoid conflicts
  • Database (SQLite works fine for personal use)
  • Domain and URL settings for your Tailscale hostname

Step 2: Configure SSH Access

Set up SSH for git operations:

# Add your SSH key to Forgejo via the web UI
# Then test access:
ssh -T git@your-server.tailnet.ts.net -p 2222

Step 3: Create Your GitOps Repository

  1. Create a new repository in Forgejo (e.g., infrastructure or homelab)
  2. Initialize the standard directory structure:
your-repo/
├── ansible/           # Host configuration
│   ├── playbooks/
│   └── roles/
├── argocd/            # Kubernetes GitOps
│   ├── apps/          # ArgoCD Applications
│   └── manifests/     # K8s manifests per service
├── pulumi/            # IaC for Tailscale, DNS
└── docs/              # Documentation
  1. Push your initial commit

Step 4: Set Up CI/CD Runner (Optional)

Forgejo Actions runs workflows defined in .forgejo/workflows/. To use it:

  1. Register a runner on your server
  2. Configure runner to access your build tools
  3. Create workflow files for builds and deployments

BlumeOps runs a Forgejo runner in Kubernetes - see forgejo for details.

Step 5: Container Registry (Optional)

If you'll build custom container images, set up zot:

  1. Install Zot on your server
  2. Configure authentication
  3. Set up TLS (via Caddy or similar)

For getting started, you can skip this and use public registries.

What You Now Have

  • Git hosting for infrastructure code
  • SSH access for git operations
  • Foundation for CI/CD workflows
  • Optionally, a private container registry

Next Steps

  • kubernetes-bootstrap - Now that you have a git repo, set up your cluster
  • Configure Forgejo webhooks for ArgoCD (after ArgoCD is running)

BlumeOps Specifics

BlumeOps' Forgejo setup includes:

  • Ansible role for installation and updates
  • SSH on port 2222, proxied via Caddy
  • Integration with ArgoCD via deploy keys
  • Forgejo runner in Kubernetes for CI/CD

See forgejo and zot for full details.