Docs pages deploy#1
Merged
Merged
Conversation
Adds a push-on-main-gated deploy job (upload-pages-artifact + deploy-pages) so the site serves at docs.pghardstorage.org. PRs still only build + preview. Needs Pages source = GitHub Actions in settings.
postgresql007
added a commit
that referenced
this pull request
Jun 24, 2026
… container publishing (v1.0.3) (#10) * docs: correct false managed-DBaaS support claims The docs repeatedly claimed pg_hardstorage "works against managed PG" (RDS, Aurora, Cloud SQL, Azure Database, Aiven, Supabase, Neon) — the comparison page even sold it as the #1 reason to choose the tool. That is false: the data plane is physical replication (a physical slot plus BASE_BACKUP), and fully-managed DBaaS do not expose BASE_BACKUP / physical replication to customers, so it cannot take a physical base backup of them. This contradicted the README and the site's how-it-works page, and a prospective user flagged it. Standardise every page on the truth: pg_hardstorage targets PostgreSQL you run yourself (bare metal, VMs, containers, Patroni, CloudNativePG). The genuine architectural advantage is no SSH / no OS access / no archive_command on the host — not managed-DBaaS support. Managed DBaaS are explicitly out of scope. Also fixes the CLI long-description source (internal/cli/wal.go) so the generated reference page does not regress. * docs: broad correctness sweep — counts, versions, CLI, crypto, status Follow-on to the managed-DBaaS fix. Five parallel audits cross-checked doc claims against the code; corrected every verifiable mismatch: Counts/versions: - storage backends "five"->"six" (scp was omitted); LLM providers "eight"->one (only the OpenAI-compatible client + a test mock are registered); CLI page count 202->216; KMS 4-vs-5 wording reconciled. - PG support: faq had PG18 "first-class from v0.9" backwards (15/16/17 are required in CI; 18 is allow-failure); release notes said the default sandbox is PG17 (it is PG18). Nonexistent/renamed CLI in tutorials & ops guides: - llm propose backup-schedule (->llm ask), restore --confirm (->--force), backup --no-compression (removed), doctor --json (->-o json), agent status (->status <deployment>), agent --step-down (planned), verify --sandbox-backend/--firecracker-* (yaml, not flags), audit export-bundle -o (->--out), `pg_hardstorage simple` (->pg_hardstorage_simple). Dropped the fictional restore second-prompt. Overstated readiness: - "wal push/fetch/list/repair are scaffold for now" — they are fully implemented (removed, source + generated page). - CNPG-I marked as shipped in the comparison + a runnable tutorial — it is v0.5 roadmap; added roadmap markers/admonition. - skill cosign-signing and --allow-unsigned-skill described as present — signing is roadmap; reworded. Crypto/signing: - AES-256-GCM-SIV claimed as the default/shipping cipher across ~12 pages — the code ships plain AES-256-GCM (repo's own SPEC_DRIFT and release notes confirm). Reframed: GCM ships today, GCM-SIV is the planned default. Kept the FIPS "BoringCrypto lacks GCM-SIV" rationale. - audit/evidence bundles and skill signatures described as cosign — they are Ed25519 (agent keyring); cosign is for release artefacts. - SLSA page aligned to the real pipeline: provenance via slsa-github-generator (.intoto.jsonl) not `cosign attest`; container images + FIPS image marked not-yet-shipped (release runs --skip=docker). - transparency-log anchoring framed as self-hosted today, external Rekor as roadmap. Source: removed the stale "scaffold" line from internal/cli/wal.go (gofmt-clean, builds). * docs(faq): record verified per-provider basis + what is not verified Web-checked (June 2026) each named managed provider against its own replication documentation; all six withhold customer-reachable BASE_BACKUP / physical replication: - RDS, Aurora: external physical replication / pg_basebackup unsupported - Cloud SQL, Azure Database: only logical replication/decoding to external consumers; physical is internal managed-HA - Neon: custom pageserver storage, no traditional pg_basebackup - Supabase (hosted): can publish logically, cannot be a physical replica Added to the FAQ: the per-provider rationale, the general BASE_BACKUP test, and an explicit "What we have not verified" admonition (list not exhaustive, vendor behaviour changes, run `wal preflight` to confirm; self-hosted distributions including self-hosted Supabase are supported). * docs: normalise stale version references to the v1.0.1 release Cross-checked all version references after a reviewer spotted v0.9.2 in the docs. Shipped packages are already correct (goreleaser versions every artifact from the git tag via {{ .Version }}). The stale strings were all in the docs/examples: - SLSA + PCI-DSS verification examples: v0.9.2 artifact/image names -> 1.0.1 (tarball, sbom, ghcr image tags). - getting-started install: v0.1.1 download URL / .deb / .rpm / docker pull / `version` output -> 1.0.1, and the tarball asset name corrected to the real versioned form pg_hardstorage_1.0.1_linux_amd64.tar.gz. - `version`-output examples (build-from-source, fips-variant) and the ldflags example: v0.9.x / v0.9.0-dev -> v1.0.x / v1.0.0-dev. - "ships / installed" capability statements (kms long-desc + generated page, source/llm-provider/tier2 plugin contracts, getting-started- simple prereq, control-plane example agent version): de-versioned or -> v1.0. Left intentionally: v1.0 release-notes historical narrative ("since v0.9"), schema-since lineage markers, the miekg/pkcs11@v1.1.1 dependency pin, and example-plugin/skill versions — none are shipped-package versions. * docs: parameterise download/verify examples with a VERSION variable So the install / SLSA / SBOM / cosign / docker examples never go stale again: each command block now sets `VERSION=1.0.1` once (with a pointer to the latest-release page) and references ${VERSION} in artifact names, release tags, and image tags. Sample `version`-*output* lines stay literal (a variable doesn't apply to printed output). Also fixed an `audit export-bundle -o` -> `--out` in the PCI-DSS evidence-bundle example (same flag bug already corrected elsewhere; -o is the output-format selector, not a file path). Files: tutorials/getting-started.md, compliance/slsa-l3-provenance.md, compliance/pci-dss.md. * release: wire GHCR container publishing + prep v1.0.3 docs Container publishing (gated, safe-by-default): - release.yml: add docker/setup-qemu + setup-buildx and gate the `--skip=docker` removal on a PUBLISH_CONTAINERS repo variable, so the release still ships binaries/.deb/.rpm/Homebrew when GHCR isn't yet enabled, and publishes signed multi-arch images once it is. - .goreleaser.yaml: add `docker_signs` (keyless cosign image signatures). - ci.yml: add a `goreleaser check` step so the release config is validated on every push (the packaging job previously only shellcheck + helm lint). Docs for v1.0.3: - SLSA page: container-images section reframed from "not yet shipped" to "wired, gated on GHCR enablement"; cosign image signatures documented as shipping once enabled, image-level SLSA provenance kept as roadmap. - CHANGELOG: new [1.0.3] — 2026-06-24 section (doc-correctness sweep + container publishing). - Example default VERSION bumped 1.0.1 -> 1.0.3; sample version outputs updated. Broken in-repo path claims fixed (file-existence audit): - pkcs11-variant.md: internal/plugin/encryption/pkcs11 -> .../kms/pkcs11 - CONTRIBUTING.md: docs/SPEC.md -> SPEC.md (repo root) - SECURITY.md: docs/operator-guide.md -> docs/operations/operator-guide.md - firecracker-sandbox.md: dropped the non-existent scripts/ firecracker-rootfs.sh claim - reference/plugins/index.md: dropped non-existent cmd/pg_hardstorage_fips * docs: regenerate CLI page + man pages from source (docs-regen) The wal/kms long-description edits changed the source; regenerate the generated artefacts so the docs-regen drift gate passes (man pages for kms/wal now reflect the source; wal.md canonical spacing restored).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The docs workflow built and validated the site (strict mkdocs + linkcheck) but never published it. This adds a deploy job that publishes the rendered
site/to GitHub Pages so the docs serve at the canonical domaindocs.pghardstorage.org(docs/CNAME+site_urlwere already in place). The deploy job is gated to push-on-main, so PRs — including from forks — only build and preview, never publish.Type
Tests
make checkpasses locally (vet + race tests)make test-integration) where touchedCompatibility
Checklist
Author: Hans-Jürgen Schönig <hs@cybertec.at>)