diff --git a/docs/how-to/how-to.md b/docs/how-to/how-to.md index 7c0d9d7..f5d6154 100644 --- a/docs/how-to/how-to.md +++ b/docs/how-to/how-to.md @@ -1,69 +1,54 @@ --- title: How-To -modified: 2026-02-22 +modified: 2026-03-06 +last-reviewed: 2026-03-06 tags: - how-to --- # How-To Guides -Task-oriented instructions for common BlumeOps operations. These guides assume you already understand the basic concepts - see [[tutorials|Tutorials]] if you're learning. - ## Deployment -| Guide | Description | -|-------|-------------| -| [[deploy-k8s-service]] | Deploy a new service to Kubernetes via ArgoCD | -| [[add-ansible-role]] | Add a new Ansible role for indri services | -| [[create-release-artifact-workflow]] | Build artifacts and publish to Forgejo packages | -| [[build-container-image]] | Build and release a custom container image via Dagger | +- [[deploy-k8s-service]] +- [[add-ansible-role]] +- [[create-release-artifact-workflow]] +- [[build-container-image]] ## Configuration -| Guide | Description | -|-------|-------------| -| [[update-tailscale-acls]] | Update Tailscale access control policies | -| [[gandi-operations]] | Manage DNS records and cycle the Gandi API token | -| [[use-pypi-proxy]] | Configure pip and publish packages to devpi | -| [[expose-service-publicly]] | Expose a service to the public internet via Fly.io + Tailscale | -| [[manage-forgejo-mirrors]] | Create mirrors, update PATs, and rotate GitHub credentials | -| [[update-documentation]] | Publish docs via build-blumeops workflow | -| [[update-tooling-dependencies]] | Monthly update cycle for prek hooks, Fly, mise, and workflow deps | +- [[update-tailscale-acls]] +- [[gandi-operations]] +- [[use-pypi-proxy]] +- [[expose-service-publicly]] +- [[manage-forgejo-mirrors]] +- [[update-documentation]] +- [[update-tooling-dependencies]] ## Knowledge Base -| Guide | Description | -|-------|-------------| -| [[review-documentation]] | Periodically review and maintain documentation | -| [[review-services]] | Periodically review services for version freshness | -| [[agent-change-process]] | C0/C1/C2 change classification and Mikado Branch Invariant | +- [[review-documentation]] +- [[review-services]] +- [[agent-change-process]] ## Operations -| Guide | Description | -|-------|-------------| -| [[connect-to-postgres]] | Connect to PostgreSQL as a superuser via psql | -| [[restart-indri]] | Safely shut down and restart indri | -| [[manage-flyio-proxy]] | Deploy, shutoff, and troubleshoot the public proxy | -| [[restore-1password-backup]] | Recover 1Password credentials from borgmatic backup | -| [[troubleshooting]] | Diagnose and fix common issues | +- [[connect-to-postgres]] +- [[restart-indri]] +- [[manage-flyio-proxy]] +- [[restore-1password-backup]] +- [[troubleshooting]] ## Forgejo -Mikado chain for migrating Forgejo from Homebrew to source-built binary. Track progress with `mise run docs-mikado migrate-forgejo-from-brew`. - - [[migrate-forgejo-from-brew]] ## Ringtail -| Guide | Description | -|-------|-------------| -| [[manage-lockfile]] | Update or lock NixOS flake inputs via Dagger | +- [[manage-lockfile]] ## Zot -Mikado chain for hardening the zot registry. Track progress with `mise run docs-mikado harden-zot-registry`. - - [[harden-zot-registry]] - [[register-zot-oidc-client]] - [[wire-ci-registry-auth]] @@ -77,8 +62,6 @@ Mikado chain for hardening the zot registry. Track progress with `mise run docs- ## Authentik -Mikado chain for deploying Authentik. Track progress with `mise run docs-mikado deploy-authentik`. - - [[deploy-authentik]] - [[build-authentik-container]] - [[provision-authentik-database]] @@ -87,8 +70,6 @@ Mikado chain for deploying Authentik. Track progress with `mise run docs-mikado ## Authentik Source Build -Mikado chain for building Authentik from a custom Nix derivation (from source). Track progress with `mise run docs-mikado build-authentik-from-source`. - - [[build-authentik-from-source]] - [[mirror-authentik-build-deps]] - [[authentik-api-client-generation]] @@ -98,8 +79,6 @@ Mikado chain for building Authentik from a custom Nix derivation (from source). ## Grafana -Mikado chain for upgrading Grafana to 12.x with kustomize and home-built containers. Track progress with `mise run docs-mikado upgrade-grafana`. - - [[upgrade-grafana]] - [[kustomize-grafana-deployment]] - [[build-grafana-container]] @@ -107,8 +86,6 @@ Mikado chain for upgrading Grafana to 12.x with kustomize and home-built contain ## Forgejo Runner -Mikado chain for upgrading the k8s forgejo-runner daemon from v6.3.1 to v12.x. Track progress with `mise run docs-mikado upgrade-k8s-runner`. - - [[upgrade-k8s-runner]] - [[validate-workflows-against-v12]] - [[review-runner-config-v12]]