diff --git a/guides/source/active_storage_overview.md b/guides/source/active_storage_overview.md index 02fdc828fe..b57bc1e90d 100644 --- a/guides/source/active_storage_overview.md +++ b/guides/source/active_storage_overview.md @@ -510,7 +510,7 @@ Direct Uploads Active Storage, with its included JavaScript library, supports uploading directly from the client to the cloud. -### Direct upload installation +### Usage 1. Include `activestorage.js` in your application's JavaScript bundle. @@ -532,7 +532,73 @@ directly from the client to the cloud. ```erb <%= form.file_field :attachments, multiple: true, direct_upload: true %> ``` -3. That's it! Uploads begin upon form submission. + +3. Configure CORS on third-party storage services to allow direct upload requests. + +4. That's it! Uploads begin upon form submission. + +### Cross-Origin Resource Sharing (CORS) configuration + +To make direct uploads to a third-party service work, you’ll need to configure the service to allow cross-origin requests from your app. Consult the CORS documentation for your service: + +* [S3](https://docs.aws.amazon.com/AmazonS3/latest/dev/cors.html#how-do-i-enable-cors) +* [Google Cloud Storage](https://cloud.google.com/storage/docs/configuring-cors) +* [Azure Storage](https://docs.microsoft.com/en-us/rest/api/storageservices/cross-origin-resource-sharing--cors--support-for-the-azure-storage-services) + +Take care to allow: + +* All origins from which your app is accessed +* The `PUT` request method +* The following headers: + * `Origin` + * `Content-Type` + * `Content-MD5` + * `Content-Disposition` (except for Azure Storage) + * `x-ms-blob-content-disposition` (for Azure Storage only) + * `x-ms-blob-type` (for Azure Storage only) + +#### Example: S3 CORS configuration + +```xml + + + + https://www.example.com + PUT + Origin + Content-Type + Content-MD5 + Content-Disposition + 3600 + + +``` + +#### Example: Google Cloud Storage CORS configuration + +```json +[ + { + "origin": ["https://www.example.com"], + "method": ["PUT"], + "responseHeader": ["Origin", "Content-Type", "Content-MD5", "Content-Disposition"], + "maxAgeSeconds": 3600 + } +] +``` + +#### Example: Azure Storage CORS configuration + +```xml + + + https://www.example.com + PUT + Origin, Content-Type, Content-MD5, x-ms-blob-content-disposition, x-ms-blob-type + 3600 + + +``` ### Direct upload JavaScript events