Merge pull request #777 from transloadit/doc/gcs

Document Google Cloud Storage setup for the AwsS3 plugin

website/src/docs/aws-s3.md

@@ -151,6 +151,82 @@ uppy-server uses POST uploads by default, but you can also use them with your ow
    })
    ```
 
+## S3 Alternatives
+
+Many other object storage providers have an identical API to S3, so you can use the AwsS3 plugin with them. To use them with Uppy Server, you can set the `UPPYSERVER_AWS_ENDPOINT` variable to the endpoint of your preferred service.
+
+### DigitalOcean Spaces
+
+For example, with DigitalOcean Spaces, you could do something like this:
+
+```bash
+export UPPYSERVER_AWS_ENDPOINT="https://{region}.digitaloceanspaces.com"
+export UPPYSERVER_AWS_BUCKET="my-space-name"
+```
+
+The `{region}` string will be replaced by the contents of the `UPPYSERVER_AWS_REGION` environment variable.
+
+For a working example that you can run and play around with, see the [digitalocean-spaces](https://github.com/transloadit/uppy/tree/master/examples/digitalocean-spaces) folder in the Uppy repository.
+
+### Google Cloud Storage
+
+For Google Cloud Storage, you need to take a few more steps. For the AwsS3 plugin to be able to upload to a GCS bucket, it needs the Interoperability setting enabled. You can enable the Interoperability setting and [generate interoperable storage access keys](https://cloud.google.com/storage/docs/migrating#keys) by going to [Google Cloud Storage](https://console.cloud.google.com/storage) » Settings » Interoperability. Then set the environment variables for Uppy Server like below:
+
+```bash
+export UPPYSERVER_AWS_ENDPOINT="https://storage.googleapis.com"
+export UPPYSERVER_AWS_BUCKET="YOUR-GCS-BUCKET-NAME"
+export UPPYSERVER_AWS_KEY="GOOGxxxxxxxxx" # The Access Key
+export UPPYSERVER_AWS_SECRET="YOUR-GCS-SECRET" # The Secret
+```
+
+You do not need to configure the region with GCS.
+
+You also need to configure CORS differently. Unlike Amazon, Google does not offer a UI for CORS configurations. Instead an HTTP API must be used. If you haven't done this already, see [Configuring CORS on a Bucket](https://cloud.google.com/storage/docs/configuring-cors#Configuring-CORS-on-a-Bucket) in the GCS documentation, or follow the below steps to do it using Google's API playground.
+
+GCS has multiple CORS formats, both XML and JSON. Unfortunately their XML format is different from Amazon's, so we can't simply use the one from the [S3 Bucket configuration](#S3-Bucket-configuration) section. Google appears to favour the JSON format, so we'll use that.
+
+#### JSON CORS Configuration
+
+The JSON format consists of an array of CORS configuration objects. An example using POST policy document uploads is shown here:
+
+```json
+{
+  "cors": [
+    {
+      "origin": ["https://my-app.com"],
+      "method": ["GET", "POST"],
+      "maxAgeSeconds": 3000
+    },
+    {
+      "origin": ["*"],
+      "method": ["GET"],
+      "maxAgeSeconds": 3000
+    }
+  ]
+}
+```
+
+Most AWS configurations should be fairly simple to port to this format. When using presigned `PUT` uploads, replace the `"POST"` method by `"PUT"` in the first entry.
+
+If you have the [gsutil](https://cloud.google.com/storage/docs/gsutil) command-line tool, you can apply this configuration using the [gsutil cors](https://cloud.google.com/storage/docs/configuring-cors#configure-cors-bucket) command.
+
+```bash
+gsutil cors set THAT-FILE.json gs://BUCKET-NAME
+```
+
+Otherwise, you can manually apply it through the OAuth playground:
+
+ 1. Get a temporary API token from the [Google OAuth2.0 playground](https://developers.google.com/oauthplayground/)
+   1. Select the "Cloud Storage JSON API v1" » "devstorage.full_control" scope
+   1. Press "Authorize APIs" and allow access
+ 1. Click "Step 3 - Configure request to API"
+ 1. Configure it like below:
+   - HTTP Method: PATCH
+   - Request URI: `https://www.googleapis.com/storage/v1/b/YOUR_BUCKET_NAME`
+   - Content-Type: application/json (should be the default)
+   - Press "Enter request body" and input your CORS configuration
+ 1. Then, finally, press "Send the request".
+
 ## Examples
 
 <a id="example-presigned-url"></a>
@@ -192,21 +268,6 @@ uppy.use(AwsS3, {
 
 See the [aws-presigned-url example in the uppy repository](https://github.com/transloadit/uppy/tree/master/examples/aws-presigned-url) for a small example that implements both the server-side and the client-side.
 
-### S3 Alternatives
-
-Many other object storage providers have an identical API to S3, so you can use the AwsS3 plugin with them. To use them with uppy-server, you can set the `UPPYSERVER_AWS_ENDPOINT` variable to the endpoint of your preferred service.
-
-For example, with DigitalOcean Spaces, you could do something like this:
-
-```
-export UPPYSERVER_AWS_ENDPOINT="https://{region}.digitaloceanspaces.com"
-export UPPYSERVER_AWS_BUCKET="my-space-name"
-```
-
-The `{region}` string will be replaced by the contents of the `UPPYSERVER_AWS_REGION` environment variable.
-
-For a working example that you can run and play around with, see the [digitalocean-spaces](https://github.com/transloadit/uppy/tree/master/examples/digitalocean-spaces) folder in the Uppy repository.
-
 ### Retrieving presign parameters of the uploaded file
 
 Once the file is uploaded, it's possible to retrieve the parameters that were