Skip to content

docs(server): add S3 storage backend operator guide (#100)#109

Merged
bigpuritz merged 1 commit into
mainfrom
feature/100_s3-storage-docs
May 13, 2026
Merged

docs(server): add S3 storage backend operator guide (#100)#109
bigpuritz merged 1 commit into
mainfrom
feature/100_s3-storage-docs

Conversation

@bigpuritz
Copy link
Copy Markdown
Contributor

Closes #100.

The 1.0.0 release notes (PR #105) called out that the new S3-compatible storage backend ships; this PR is the operator-facing reference — what it is, all eight PLUGWERK_STORAGE_* env vars, four pasteable provider examples, and the migration playbooks (with the loud footgun warning).

Files changed

File What
src/content/docs/server/storage.mdx (new) Full operator guide (~250 lines)
server/configuration.mdx Storage section shrinks from a four-line table to a one-paragraph pointer
server/deployment.mdx One sentence after the Run-options table pointing at the storage page
astro.config.mjs New "Storage backends" sidebar entry between Deployment and Configuration

What the new page covers

  1. Choosing a backend — matrix mapping use cases (single-node Compose, multi-replica Kubernetes, cloud-managed serverless, DR, SaaS multi-tenant) to fs vs s3.
  2. Filesystem (fs) — preserves the existing operator notes (default path, container-user permissions, key layout <namespace-uuid>:<plugin-id>:<version>:<extension>).
  3. S3-compatible (s3) — full env-var table with the half-configured-credentials <Aside> (one set, one blank → rejected at startup) and the AWS DefaultCredentialsProvider fallback for the both-blank case.
  4. Provider examples in <Tabs>: AWS S3 + IRSA / MinIO / Cloudflare R2 / Hetzner Object Storage. Every block highlights the three knobs that vary by provider (endpoint, region, path-style-access).
  5. Migration between backends — opens with a prominent <Aside type="caution"> warning that flipping PLUGWERK_STORAGE_TYPE alone breaks every existing download with HTTP 404. Both directions documented (fs → s3 in <Tabs> for AWS CLI vs MinIO client; s3 → fs symmetric).
  6. Verifying the migration — points at the live Admin → Storage Consistency UI (issue body's "Until #190 lands" wording is stale — the consistency check shipped in v1.0.0). CLI sanity-check fallback for environments without UI access.
  7. What's not supported — explicit list (pre-signed direct uploads, GCS / Azure Blob native APIs, multi-bucket setups).

Sidebar position

Between Deployment and Configuration in the Server Administration group — mirrors the operator's mental flow: deploy → choose storage → configure → secure → operate.

Source verification

Every claim about the backend (key layout, half-configured-credentials rejection, fail-fast probe wording, the four supported providers, ConsistencyService availability) verified against ADR-0034 in the upstream repo at v1.0.0. Source files read for accuracy, not cited in the docs (per AGENTS.md no-internal-link rule). Internal-link grep returns 0 hits in the new content.

Acceptance criteria from #100

  • Backend overview page lives at a discoverable URL under /server//server/storage/
  • Every PLUGWERK_STORAGE_* env var is in the configuration reference (including the half-configured-credentials gotcha and the path-style-access MinIO note)
  • All four provider examples (AWS, MinIO, R2, Hetzner) are pasteable
  • Migration page contains both directions with working CLI commands
  • The "switching breaks existing downloads" footgun is in a callout box, not buried mid-paragraph
  • Cross-links from the deployment + env-var reference pages

Departure from the issue text

  • Single page instead of three (/server/storage/, .../configuration/, .../migration/). One operator-mental-model page is easier to read and maintain than three fragments. Other Server Administration topics are also single pages — consistency wins.
  • "Until #190 lands" wording dropped — the consistency service shipped in v1.0.0; verifying-the-migration section points at the live UI instead.

Test plan

  • npm run format clean
  • npm run format:check clean
  • npm run build clean (33 pages — +1 new storage page)
  • AGENTS.md ADR/internal-PR grep clean in new content
  • Storage page renders, all <Aside> and <Tabs> blocks build correctly
  • Cross-links from /server/configuration/ and /server/deployment/ resolve to /server/storage/
  • Reviewer: open /server/storage/, verify the migration <Aside type="caution"> is visually prominent (not buried), the four provider tabs all render with correct content, and the table reads cleanly on mobile
  • Reviewer: verify the sidebar shows the new entry in the right slot of the Server Administration group
  • Reviewer: spot-check one of the provider examples against the upstream .env.example to confirm wording matches

Out of scope

New /server/storage/ page covering Plugwerk's pluggable storage
backend (fs default + s3-compatible) for v1.0.0. Operators reaching
plugwerk.io for S3 setup now have a complete reference instead of
the four-line stub that previously lived in configuration.mdx.

src/content/docs/server/storage.mdx (new, ~250 lines):

- "Choosing a backend" matrix — single-node Docker / Kubernetes /
  cloud-managed / DR / SaaS use cases mapped to fs vs s3.
- Filesystem section preserves the existing operator notes (default
  path, container-user permissions, key layout
  `<namespace-uuid>:<plugin-id>:<version>:<extension>`).
- S3 configuration: full table of all eight `PLUGWERK_STORAGE_*`
  variables with the half-configured-credentials Aside (one set,
  one blank → rejected at startup) and the AWS DefaultCredentialsProvider
  fallback for the both-blank case.
- Provider examples in <Tabs>: AWS S3 + IRSA, MinIO, Cloudflare R2,
  Hetzner Object Storage. Each block highlights the three knobs that
  actually vary by provider (endpoint, region, path-style-access).
- Migration between backends opens with a prominent <Aside
  type="caution"> warning that flipping `PLUGWERK_STORAGE_TYPE`
  alone breaks every existing download with HTTP 404. Both
  directions documented (fs → s3 in <Tabs> for AWS CLI vs MinIO
  client; s3 → fs symmetric).
- "Verifying the migration" points at the live Admin → Storage
  Consistency UI (issue body's "Until #190 lands" wording is stale —
  the consistency check shipped in v1.0.0). CLI sanity-check fallback
  for environments without UI access.
- "What's not supported" is explicit: pre-signed direct uploads,
  GCS / Azure Blob native APIs, multi-bucket setups.
- Trailing related-pages block.

server/configuration.mdx:

- Storage section shrinks from a four-line table to a one-paragraph
  pointer at /server/storage/. The detailed env-var coverage now
  lives on the dedicated page.

server/deployment.mdx:

- Single sentence after the Run-options table pointing at the storage
  page for the s3-backed multi-replica / cloud-managed scenarios
  where a persistent volume is impractical.

astro.config.mjs:

- New "Storage backends" sidebar entry between Deployment and
  Configuration in the Server Administration group — mirrors the
  operator's mental flow (deploy → choose storage → configure →
  secure → operate).

Source verification: every claim about the backend (key layout,
half-configured-credentials rejection, fail-fast probe wording, the
four supported providers) verified against ADR-0034 in the upstream
repo at v1.0.0. Source read for accuracy, not cited (per AGENTS.md
no-internal-link rule). Internal-link grep returns 0 hits in the new
content.

Verification:
- npm run format / format:check / build all green (33 pages, +1)
- AGENTS.md ADR/internal-PR grep clean in new content
- Storage page renders, all <Aside>/<Tabs> blocks build correctly
- Cross-links from /server/configuration/ and /server/deployment/
  resolve to /server/storage/

Closes #100
@bigpuritz bigpuritz added this to the 1.0.0 milestone May 13, 2026
@bigpuritz bigpuritz added documentation Improvements or additions to documentation enhancement New feature or request labels May 13, 2026
@bigpuritz bigpuritz merged commit eec0ded into main May 13, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: S3-compatible storage backend — operator guide + env vars + fs↔s3 migration

1 participant