Skip to content

docs: Make file-upload storage setup the default path for S3, GCP, and R2 - #763

Merged
developerjamiu merged 2 commits into
serverpod:mainfrom
abdulawalarif:docs/improve-pubdev-readiness
Aug 27, 2026
Merged

docs: Make file-upload storage setup the default path for S3, GCP, and R2#763
developerjamiu merged 2 commits into
serverpod:mainfrom
abdulawalarif:docs/improve-pubdev-readiness

Conversation

@abdulawalarif

@abdulawalarif abdulawalarif commented Aug 25, 2026

Copy link
Copy Markdown
Contributor

serverpod/serverpod#3470 is a pub.dev packaging audit. This PR updates the File uploads page so it is the canonical setup path those packages can link to. It does not close that issue.

S3, GCP, and R2 each get one default setup path. Native GCP and custom S3-compatible endpoints stay as labelled variants. The GCP HMAC region example is us-central1 instead of auto.

Rebased onto main after #765. The Upload a file and Access stored files sections keep the renamed storage API. Unsupported options, including preventOverwrite on providers that do not support it, throw.

Test plan

  • Open Next → Concepts → Endpoints & APIs → File uploads.
  • Confirm Upload a file and Access stored files still use the renamed storage API from docs: Document updated cloud storage interface #765.
  • Walk HMAC GCP, native GCP, S3, and R2: install, import, constructor, and passwords or env vars.
  • Confirm the custom S3-compatible section is last and is not the default path.
  • Check links to Configuration, Sessions, pub.dev packages, GCP HMAC keys, and Cloudflare R2 tokens.

@developerjamiu

developerjamiu commented Aug 26, 2026

Copy link
Copy Markdown
Contributor

Closes serverpod/serverpod#3470 points at "Improve pub.dev readiness for all Serverpod packages", an open framework issue about package READMEs and pub scores. Cross-repo closing keywords fire, so merging this would close it. Remove the line.

Comment thread docs/06-concepts/02-endpoints-and-apis/07-file-uploads.md Outdated
Comment thread docs/06-concepts/02-endpoints-and-apis/07-file-uploads.md
Comment thread docs/06-concepts/02-endpoints-and-apis/07-file-uploads.md Outdated
@abdulawalarif

abdulawalarif commented Aug 26, 2026

Copy link
Copy Markdown
Contributor Author

Thanks for the review:
I addressed the suggestions.

@developerjamiu

Copy link
Copy Markdown
Contributor

The storage API was renamed in serverpod/serverpod#5621 yesterday, and #765 updated this page on main this morning. That's why the branch conflicts now.

The overlap is the first two sections, "Upload a file" and "Access stored files". Main has rewritten both for the new API, so your edits there aren't needed any more.

The rest of your work still applies: the provider sections, the passwords.yaml examples, the pub.dev links, and the us-central1 fix. Rebase on main and keep those.

Line 33 also needs dropping. It says S3 and HMAC GCP ignore preventOverwrite, which was correct when you wrote it. It now throws instead, and main has the new wording.

…d R2

Give each provider a single setup path, document s3_compat as a building block, and correct the GCP HMAC region and preventOverwrite behavior.
Label the unrestricted path example, restore fromServiceAccountJson, and warn against root-user AWS keys.
@abdulawalarif
abdulawalarif force-pushed the docs/improve-pubdev-readiness branch from 393db97 to 7552dfc Compare August 27, 2026 11:11
@abdulawalarif

Copy link
Copy Markdown
Contributor Author

The branch is rebased, and the old preventOverwrite ignore wording is gone

@developerjamiu developerjamiu added the documentation Improvements or additions to documentation label Aug 27, 2026
@developerjamiu
developerjamiu merged commit 998bd4b into serverpod:main Aug 27, 2026
7 checks 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

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants