docs(server): add S3 storage backend operator guide (#100)#109
Merged
Conversation
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
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
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.
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
src/content/docs/server/storage.mdx(new)server/configuration.mdxserver/deployment.mdxastro.config.mjsWhat the new page covers
fsvss3.fs) — preserves the existing operator notes (default path, container-user permissions, key layout<namespace-uuid>:<plugin-id>:<version>:<extension>).s3) — full env-var table with the half-configured-credentials<Aside>(one set, one blank → rejected at startup) and the AWSDefaultCredentialsProviderfallback for the both-blank case.<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).<Aside type="caution">warning that flippingPLUGWERK_STORAGE_TYPEalone breaks every existing download with HTTP 404. Both directions documented (fs → s3 in<Tabs>for AWS CLI vs MinIO client; s3 → fs symmetric).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
/server/—/server/storage/PLUGWERK_STORAGE_*env var is in the configuration reference (including the half-configured-credentials gotcha and the path-style-access MinIO note)Departure from the issue text
/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.Test plan
npm run formatcleannpm run format:checkcleannpm run buildclean (33 pages — +1 new storage page)<Aside>and<Tabs>blocks build correctly/server/configuration/and/server/deployment/resolve to/server/storage//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.env.exampleto confirm wording matchesOut of scope
# --- S3-compatible storage ---section from.env.examplevia theenvExampleSectionhelper from PR feat(docs): consume .env.example from plugwerk on every release (#101) #108 — depends on feat(docs): consume .env.example from plugwerk on every release (#101) #108 landing first; can be added as a small follow-up once that helper is in main. The page already points operators at the full.env.examplereference at the bottom of the Configuration page.