jedarden/pdftract
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
pdftract/notes/pdftract-26pc.md
jedarden 063ee268d9 docs(pdftract-26pc): add verification note for pdftract-docs-build template 
Documents the Argo WorkflowTemplate implementation for building and
deploying mdBook documentation to Cloudflare Pages at pdftract.com.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-23 23:46:51 -04:00

3.2 KiB
Raw Blame History

pdftract-26pc: Argo WorkflowTemplate pdftract-docs-build

Summary

Created the Argo WorkflowTemplate pdftract-docs-build that builds mdBook documentation and deploys to Cloudflare Pages.

Implementation

File Created

  • jedarden/declarative-config/k8s/iad-ci/argo-workflows/pdftract-docs-build.yaml

Template Features

  1. Build Process

    • Clones pdftract repo at specified tag
    • Installs mdBook and mdbook-linkcheck via cargo (cached in emptyDir for speed)
    • Runs mdbook-linkcheck with fail-on-internal-error policy
    • Builds mdBook to docs/user-docs/build/user-docs/
    • Validates build output (index.html, schema directory)

  2. Cloudflare Pages Deploy

    • Uses wrangler to deploy build/user-docs/ directory
    • Project name: pdftract-com
    • Branch: set to $TAG for metadata
    • Uses --commit-dirty=true for non-git deployments

  3. Secret Management

    • Cloudflare API token from ExternalSecret cloudflare-pages-secret
    • Key: CF_API_TOKEN
    • Sourced from OpenBao via ESO (rs-manager/iad-ci/cloudflare/pages)

  4. Idempotency

    • Re-running against same tag overwrites deployment cleanly
    • Uses wrangler's default deploy behavior

  5. Resource Limits

    • Requests: 500m CPU, 1Gi memory
    • Limits: 2000m CPU, 4Gi memory
    • Active deadline: 1200 seconds (20 minutes)

ArgoCD Integration

  • Template lives in k8s/iad-ci/argo-workflows/ directory
  • Synced via ArgoCD Application argo-workflows-ns-iad-ci
  • Auto-sync enabled with prune and self-heal

Acceptance Criteria

PASS

  • k8s/iad-ci/argo-workflows/pdftract-docs-build.yaml exists in declarative-config
  • Template synced via ArgoCD (included in argo-workflows-ns-iad-ci app)
  • Cloudflare token sourced from OpenBao via ESO (cloudflare-pages-secret)
  • Template is re-runnable (wrangler overwrites on deploy)
  • Uses proper secret reference (CF_API_TOKEN from cloudflare-pages-secret)

WARN (Infrastructure constraints)

  • Manual workflow submission testing - requires kubectl access to iad-ci cluster
  • Milestone tag deployment verification - requires actual milestone tag and Cloudflare Pages setup

FAIL

  • None

Git Commits

  • declarative-config: c51ff5f fix(pdftract-26pc): correct docs build paths and Cloudflare Pages config

Notes

The template follows the same pattern as website-build-workflowtemplate.yml:

  • Uses wrangler for Cloudflare Pages deploy
  • References the same shared cloudflare-pages-secret ExternalSecret
  • Uses Rust base image (rust:1.83-slim) for cargo tooling

Key difference from generic website-build:

  • Specialized for pdftract docs (hardcoded repo, build command, output dir)
  • Includes mdbook-linkcheck validation step
  • Builds mdBook instead of npm-based sites

Cloudflare Pages Configuration

  • Project: pdftract-com
  • Domain: pdftract.com (DNS configured separately)
  • Production branch: Configured in Cloudflare Pages dashboard
  • Account ID: e26f015c7ba47a6ad6219385e77072b7

Trigger

The template is designed to be triggered on milestone tags (e.g., v0.3.0) via the pdftract-release-cascade workflow, which chains pdftract-crates-publish before this template to ensure docs.rs links resolve.