docs: Make file-upload storage setup the default path for S3, GCP, and R2 - #763
docs: Make file-upload storage setup the default path for S3, GCP, and R2#763abdulawalarif wants to merge 2 commits into
Conversation
…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.
|
|
| There are a few steps required to upload a file. First, you must create an upload description on the server and pass it to your app. The upload description grants access to the app to upload the file. If you want to grant access to any file, you can add the following code to one of your endpoints. However, in most cases, you may want to restrict which files can be uploaded. | ||
| ### Create an upload description | ||
|
|
||
| Create an upload description on the server and pass it to the app. The description grants the app permission to upload that file. Restrict who can request one. |
There was a problem hiding this comment.
Line 13 says "Do not accept an arbitrary client path", but both samples below take path from the caller and pass it straight through. The previous version labelled the first sample as the deliberately unrestricted one, and that sentence is gone.
| Create an upload description on the server and pass it to the app. The description grants the app permission to upload that file. Restrict who can request one. | |
| Create an upload description on the server and pass it to the app. The description grants the app permission to upload that file. Restrict who can request one. The example below accepts whatever path it is given. Build the path on the server rather than copying it as-is. |
| ``` | ||
|
|
||
| For environments that support Application Default Credentials (e.g. Google Compute Engine, Cloud Run), use `fromApplicationDefaultCredentials`: | ||
| On Google Compute Engine or Cloud Run, use Application Default Credentials instead: |
There was a problem hiding this comment.
This section previously documented a third constructor, fromServiceAccountJson, for passing the JSON directly. It still exists at native_google_cloud_storage.dart:97, and the other two constructors survived the rewrite.
| On Google Compute Engine or Cloud Run, use Application Default Credentials instead: | |
| To pass the JSON directly instead, use `fromServiceAccountJson`: | |
| ```dart | |
| pod.addCloudStorage( | |
| await gcp.NativeGoogleCloudStorage.fromServiceAccountJson( | |
| storageId: 'public', | |
| public: true, | |
| bucket: 'my-bucket-name', | |
| serviceAccountJson: myServiceAccountJson, | |
| ), | |
| ); | |
| ``` | |
| On Google Compute Engine or Cloud Run, use Application Default Credentials instead: |
| ### AWS S3 | ||
| ### Configure AWS S3 | ||
|
|
||
| Create an S3 bucket and an IAM user whose access is limited to that bucket. Put CloudFront in front of the bucket if you want a custom domain and TLS certificate. Add the access keys to `config/passwords.yaml`, or pass them as `SERVERPOD_AWS_ACCESS_KEY_ID` and `SERVERPOD_AWS_SECRET_KEY`. |
There was a problem hiding this comment.
The old S3 section ended with "Avoid root-user access keys." The IAM-user half made it into this rewrite, but that warning is the part that stops someone reaching for their root keys.
| Create an S3 bucket and an IAM user whose access is limited to that bucket. Put CloudFront in front of the bucket if you want a custom domain and TLS certificate. Add the access keys to `config/passwords.yaml`, or pass them as `SERVERPOD_AWS_ACCESS_KEY_ID` and `SERVERPOD_AWS_SECRET_KEY`. | |
| Create an S3 bucket and an IAM user whose access is limited to that bucket. Avoid root-user access keys. Put CloudFront in front of the bucket if you want a custom domain and TLS certificate. Add the access keys to `config/passwords.yaml`, or pass them as `SERVERPOD_AWS_ACCESS_KEY_ID` and `SERVERPOD_AWS_SECRET_KEY`. |
Label the unrestricted path example, restore fromServiceAccountJson, and warn against root-user AWS keys.
|
Thanks for the review: |
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-central1instead ofauto, andpreventOverwriteis documented as enforced on native GCP and R2, and ignored on S3 and HMAC GCP.Test plan