Deploying to Amazon S3 – Gatsby Cloud

Gatsby Cloud integrates with Amazon S3, which is a storage service that can be used for hosting a Gatsby site so you can build and deploy seamlessly.

Prerequisites

This guide assumes you already:

have an Amazon S3 bucket to deploy to
have a Gatsby Cloud site created

You can use either of the following site creation options if you don't have one already:

Setting Up the Hosting Integration

Once your site is available inside Gatsby Cloud you can "view details" and navigate to the "Site Settings" tab.

Inside Site Settings there is an "Integrations" link. Select this menu item and scroll down to the section titled "Hosting Integrations".

This is where you'll see the AWS S3 logo. Click the "Connect" button to the right of that logo and you'll be prompted to add some information:

Access Key ID
Secret Access Key
Bucket Name
File Key Prefix (Optional) (the bucket "subfolder" where the build output files should be deployed )
CloudFront Distribution ID (Optional)
CloudFront Invalidation Paths (Optional)

Once you hit save, builds will automatically be deployed to the bucket with the bucket name you provided.

Configuring Bucket Settings

Refer to the AWS docs on using a bucket for static hosting for more information on configuring specific settings for your bucket in the AWS Console.

Some options you might need to update are enabling "Static website hosting" in the "Properties" tab of your bucket. You will also need to configure permissions to make files inside the bucket publicly accessible.

Granting Gatsby Cloud Minimum Required Permissions

To get the Access Key ID and Secret Access Key, you'll have to create a new set of keys from the AWS IAM service. IAM enables you to manage access to AWS services and resources securely.

You'll need to create a user with access to S3. To remain the most secure, you should create a user and key that is used only specifically for the purpose of deploying from Gatsby Cloud, and that only has access to the bucket to which you are deploying.

You can use this policy to grant Gatsby Cloud the minimum permissions it needs to deploy to S3, changing MY-BUCKET-NAME to your actual bucket name.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["s3:GetBucketLocation"],
      "Resource": ["arn:aws:s3:::*"]
    },
    {
      "Effect": "Allow",
      "Action": ["s3:ListBucket"],
      "Resource": "arn:aws:s3:::MY-BUCKET-NAME"
    },
    {
      "Effect": "Allow",
      "Action": ["s3:PutObject", "s3:GetObject", "s3:DeleteObject"],
      "Resource": "arn:aws:s3:::MY-BUCKET-NAME/*"
    }
  ]
}

Finishing Up

And that's it! Your site is now set up to build and deploy. Gatsby Cloud will handle everything for you. You can make edits to which bucket is being deployed to by going back to the "Hosting Integrations" section.

Note that you can only have one hosting integration. If you choose to configure another provider, that will override your existing Amazon S3 integration.

FAQ

Can I put a CDN in front of my S3 bucket?

Yes, you can configure Amazon Cloudfront to serve the files in your S3 bucket, or connect a bucket to another preferred CDN.

If you use CloudFront as a CDN, you can set the "CloudFront Distribution ID" and "CloudFront Invalidation Paths" in your integration configuration.

If you set the distribution ID, Gatsby Cloud will automatically create a cache invalidation in CloudFront for that ID. You can also set invalidation paths to specify which paths CloudFront should invalidate. This should be a comma separated string of paths. For example, you could enter /webpack.stats.json,/chunk-map.json to only invalidate those two files. If you leave invalidations paths blank, Gatsby Cloud will create a cache invalidation for /* which will invalidate all files in your CloudFront distribution.

In order for Gatsby Cloud to have permissions to create a CloudFront cache invalidation, you must add a new policy to the user you created above. To remain the most secure, only grant access for Gatsby Cloud to create a cache invalidation.

Note that AWS does not allow resource level restrictions when creating a cache invalidation. This is a limitation of AWS and not Gatsby Cloud.

You can use this policy to grant Gatsby Cloud the minimum required permissions for CloudFront cache invalidation.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["cloudfront:CreateInvalidation"],
      "Resource": "*"
    }
  ]
}