From 27d8f3cf1f6372009fda584da8f14d07b0bcb5ba Mon Sep 17 00:00:00 2001 From: Erich Blume Date: Tue, 17 Feb 2026 07:29:33 -0800 Subject: [PATCH] Review gandi-operations doc and reorganize how-to guides (#200) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Summary - **Doc review:** Reviewed `gandi-operations.md` — added `last-reviewed` frontmatter, verified all wiki-links, confirmed Pulumi state has no drift - **Gandi reference fix:** Added missing `cv.eblu.me` CNAME row to `gandi.md` DNS records table (was present in Pulumi but undocumented) - **Pulumi comment fix:** Updated stale `README.md` reference in `__main__.py` to point to `docs/how-to/gandi-operations.md` - **How-to reorg:** Moved 14 how-to guides into 3 subdirectories (`deployment/`, `configuration/`, `operations/`), collapsed the Documentation and Database index sections into Configuration and Operations respectively ## Verification - `docs-check-links` — all 180 wiki-links valid - `docs-check-filenames` — all 90 filenames unique - `dns-preview` — 5 resources unchanged, no drift - All pre-commit hooks pass ## Test plan - [ ] Verify docs site builds correctly with new paths - [ ] Spot-check a few wiki-links from other pages to moved how-to guides Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/200 --- .../review-gandi-operations-and-howto-reorg.doc.md | 1 + .../{ => configuration}/expose-service-publicly.md | 0 .../how-to/{ => configuration}/gandi-operations.md | 3 ++- .../{ => configuration}/update-documentation.md | 0 .../{ => configuration}/update-tailscale-acls.md | 0 docs/how-to/{ => configuration}/use-pypi-proxy.md | 0 docs/how-to/{ => deployment}/add-ansible-role.md | 0 .../{ => deployment}/build-container-image.md | 0 .../create-release-artifact-workflow.md | 0 docs/how-to/{ => deployment}/deploy-k8s-service.md | 0 docs/how-to/how-to.md | 14 ++------------ .../how-to/{ => operations}/connect-to-postgres.md | 0 docs/how-to/{ => operations}/manage-flyio-proxy.md | 0 docs/how-to/{ => operations}/restart-indri.md | 0 .../{ => operations}/restore-1password-backup.md | 0 docs/how-to/{ => operations}/troubleshooting.md | 0 docs/reference/infrastructure/gandi.md | 3 ++- pulumi/gandi/__main__.py | 2 +- 18 files changed, 8 insertions(+), 15 deletions(-) create mode 100644 docs/changelog.d/review-gandi-operations-and-howto-reorg.doc.md rename docs/how-to/{ => configuration}/expose-service-publicly.md (100%) rename docs/how-to/{ => configuration}/gandi-operations.md (97%) rename docs/how-to/{ => configuration}/update-documentation.md (100%) rename docs/how-to/{ => configuration}/update-tailscale-acls.md (100%) rename docs/how-to/{ => configuration}/use-pypi-proxy.md (100%) rename docs/how-to/{ => deployment}/add-ansible-role.md (100%) rename docs/how-to/{ => deployment}/build-container-image.md (100%) rename docs/how-to/{ => deployment}/create-release-artifact-workflow.md (100%) rename docs/how-to/{ => deployment}/deploy-k8s-service.md (100%) rename docs/how-to/{ => operations}/connect-to-postgres.md (100%) rename docs/how-to/{ => operations}/manage-flyio-proxy.md (100%) rename docs/how-to/{ => operations}/restart-indri.md (100%) rename docs/how-to/{ => operations}/restore-1password-backup.md (100%) rename docs/how-to/{ => operations}/troubleshooting.md (100%) diff --git a/docs/changelog.d/review-gandi-operations-and-howto-reorg.doc.md b/docs/changelog.d/review-gandi-operations-and-howto-reorg.doc.md new file mode 100644 index 0000000..13bc4a2 --- /dev/null +++ b/docs/changelog.d/review-gandi-operations-and-howto-reorg.doc.md @@ -0,0 +1 @@ +Reorganize how-to guides into `deployment/`, `configuration/`, and `operations/` subdirectories; review and update gandi-operations doc; fix missing cv.eblu.me CNAME in gandi reference card. diff --git a/docs/how-to/expose-service-publicly.md b/docs/how-to/configuration/expose-service-publicly.md similarity index 100% rename from docs/how-to/expose-service-publicly.md rename to docs/how-to/configuration/expose-service-publicly.md diff --git a/docs/how-to/gandi-operations.md b/docs/how-to/configuration/gandi-operations.md similarity index 97% rename from docs/how-to/gandi-operations.md rename to docs/how-to/configuration/gandi-operations.md index 83b4bd4..0be00dc 100644 --- a/docs/how-to/gandi-operations.md +++ b/docs/how-to/configuration/gandi-operations.md @@ -1,6 +1,7 @@ --- title: Gandi Operations -modified: 2026-02-08 +modified: 2026-02-17 +last-reviewed: 2026-02-17 tags: - how-to - dns diff --git a/docs/how-to/update-documentation.md b/docs/how-to/configuration/update-documentation.md similarity index 100% rename from docs/how-to/update-documentation.md rename to docs/how-to/configuration/update-documentation.md diff --git a/docs/how-to/update-tailscale-acls.md b/docs/how-to/configuration/update-tailscale-acls.md similarity index 100% rename from docs/how-to/update-tailscale-acls.md rename to docs/how-to/configuration/update-tailscale-acls.md diff --git a/docs/how-to/use-pypi-proxy.md b/docs/how-to/configuration/use-pypi-proxy.md similarity index 100% rename from docs/how-to/use-pypi-proxy.md rename to docs/how-to/configuration/use-pypi-proxy.md diff --git a/docs/how-to/add-ansible-role.md b/docs/how-to/deployment/add-ansible-role.md similarity index 100% rename from docs/how-to/add-ansible-role.md rename to docs/how-to/deployment/add-ansible-role.md diff --git a/docs/how-to/build-container-image.md b/docs/how-to/deployment/build-container-image.md similarity index 100% rename from docs/how-to/build-container-image.md rename to docs/how-to/deployment/build-container-image.md diff --git a/docs/how-to/create-release-artifact-workflow.md b/docs/how-to/deployment/create-release-artifact-workflow.md similarity index 100% rename from docs/how-to/create-release-artifact-workflow.md rename to docs/how-to/deployment/create-release-artifact-workflow.md diff --git a/docs/how-to/deploy-k8s-service.md b/docs/how-to/deployment/deploy-k8s-service.md similarity index 100% rename from docs/how-to/deploy-k8s-service.md rename to docs/how-to/deployment/deploy-k8s-service.md diff --git a/docs/how-to/how-to.md b/docs/how-to/how-to.md index 81f887a..bd8f2b0 100644 --- a/docs/how-to/how-to.md +++ b/docs/how-to/how-to.md @@ -1,6 +1,6 @@ --- title: How-To -modified: 2026-02-14 +modified: 2026-02-17 tags: - how-to --- @@ -26,11 +26,6 @@ Task-oriented instructions for common BlumeOps operations. These guides assume y | [[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 | - -## Documentation - -| Guide | Description | -|-------|-------------| | [[update-documentation]] | Publish docs via build-blumeops workflow | ## Knowledge Base @@ -40,16 +35,11 @@ Task-oriented instructions for common BlumeOps operations. These guides assume y | [[review-documentation]] | Periodically review and maintain documentation | | [[review-services]] | Periodically review services for version freshness | -## Database - -| Guide | Description | -|-------|-------------| -| [[connect-to-postgres]] | Connect to PostgreSQL as a superuser via psql | - ## 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 | diff --git a/docs/how-to/connect-to-postgres.md b/docs/how-to/operations/connect-to-postgres.md similarity index 100% rename from docs/how-to/connect-to-postgres.md rename to docs/how-to/operations/connect-to-postgres.md diff --git a/docs/how-to/manage-flyio-proxy.md b/docs/how-to/operations/manage-flyio-proxy.md similarity index 100% rename from docs/how-to/manage-flyio-proxy.md rename to docs/how-to/operations/manage-flyio-proxy.md diff --git a/docs/how-to/restart-indri.md b/docs/how-to/operations/restart-indri.md similarity index 100% rename from docs/how-to/restart-indri.md rename to docs/how-to/operations/restart-indri.md diff --git a/docs/how-to/restore-1password-backup.md b/docs/how-to/operations/restore-1password-backup.md similarity index 100% rename from docs/how-to/restore-1password-backup.md rename to docs/how-to/operations/restore-1password-backup.md diff --git a/docs/how-to/troubleshooting.md b/docs/how-to/operations/troubleshooting.md similarity index 100% rename from docs/how-to/troubleshooting.md rename to docs/how-to/operations/troubleshooting.md diff --git a/docs/reference/infrastructure/gandi.md b/docs/reference/infrastructure/gandi.md index a255474..c374b05 100644 --- a/docs/reference/infrastructure/gandi.md +++ b/docs/reference/infrastructure/gandi.md @@ -1,6 +1,6 @@ --- title: Gandi -modified: 2026-02-08 +modified: 2026-02-17 tags: - infrastructure - networking @@ -42,6 +42,7 @@ Both records point to [[indri]], which runs [[caddy]] as the reverse proxy for a | Record | Type | Value | TTL | |--------|------|-------|-----| | `docs.eblu.me` | CNAME | `blumeops-proxy.fly.dev` | 300s | +| `cv.eblu.me` | CNAME | `blumeops-proxy.fly.dev` | 300s | Public CNAMEs point to [[flyio-proxy]] on Fly.io. See [[expose-service-publicly]] for adding new public services. diff --git a/pulumi/gandi/__main__.py b/pulumi/gandi/__main__.py index 1ae0a65..df6ad34 100644 --- a/pulumi/gandi/__main__.py +++ b/pulumi/gandi/__main__.py @@ -8,7 +8,7 @@ This program manages DNS records for blumeops infrastructure: Authentication: Set GANDI_PERSONAL_ACCESS_TOKEN environment variable. - See README.md for PAT management instructions. + See docs/how-to/gandi-operations.md for PAT management instructions. """ import os