Hosting a Gatsby Site on AWS S3 with CloudFront

This guide provides a complete workflow for deploying a static Gatsby website on AWS. The architecture uses an S3 bucket for storage and a CloudFront distribution as a global Content Delivery Network (CDN) for high performance and low latency.

---

Architecture Benefits

• Performance: CloudFront caches site assets at edge locations worldwide, drastically reducing load times for global users.
• Scalability: The serverless nature of S3 and CloudFront handles traffic spikes automatically without server management.
• Cost-Efficiency: You pay only for S3 storage and CloudFront data transfer, which is significantly cheaper than traditional server hosting for static sites.
• Security: CloudFront integrates with AWS Certificate Manager (ACM) to provide free SSL/TLS certificates and with AWS WAF for application-layer protection.

---

Prerequisites

• An AWS Account with access to S3, CloudFront, Route 53, and ACM.
• A finished Gatsby project ready for deployment.
• Node.js and the Gatsby CLI (npm install -g gatsby-cli) installed locally.
• AWS CLI installed and configured with your credentials.

---

1. Configure S3 Bucket for Static Hosting

The S3 bucket will store the static assets generated by the Gatsby build process.

Create the Bucket

1. Navigate to the S3 console in AWS.
2. Click Create bucket.
3. Enter a globally unique bucket name. For custom domains, using the domain name (e.g., www.your-site.com) is a common convention.
4. Select an AWS Region.
5. Disable "Block all public access" by unchecking the box and acknowledging the warning. This is required for CloudFront to access bucket objects.
6. Click Create bucket.

Enable Static Website Hosting

1. Select the bucket and navigate to the Properties tab.
2. Scroll to Static website hosting and click Edit.
3. Select Enable.
4. Set the Index document to index.html.
5. Set the Error document to 404.html.
6. Save changes.

Apply a Public-Read Bucket Policy

1. Navigate to the Permissions tab.
2. In the Bucket policy section, click Edit.
3. Paste the following JSON policy, replacing YOUR_BUCKET_NAME with your bucket's name. This policy allows anyone to read the objects in your bucket.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "PublicReadGetObject",
            "Effect": "Allow",
            "Principal": "*",
            "Action": "s3:GetObject",
            "Resource": "arn:aws:s3:::YOUR_BUCKET_NAME/*"
        }
    ]
}

2. Build and Deploy to S3

First, generate the production build of your Gatsby site. This compiles all necessary files into a public directory.

# From your project's root directory
gatsby build

Next, use the AWS CLI to sync the contents of the public directory to your S3 bucket.

# Syncs the build output to S3
aws s3 sync public/ s3://YOUR_BUCKET_NAME --delete

• The sync command is efficient, only uploading new or changed files.
• The --delete flag removes files from the S3 bucket that are no longer in your local public folder.

3. Create a CloudFront Distribution

CloudFront will serve your site's content from its global network, pulling from the S3 bucket as its origin.

• Navigate to the CloudFront console and click Create a CloudFront distribution.
• For Origin domain, select your S3 bucket from the dropdown. The URL should be similar to your-bucket-name.s3.amazonaws.com.
• Under Viewer protocol policy, select Redirect HTTP to HTTPS to enforce secure connections.
• In the Settings section, set the Default root object to index.html.
• (Optional) To use a custom domain, add it under Alternate domain name (CNAMEs). For SSL, you must first request a public certificate from AWS Certificate Manager (ACM) in the us-east-1 region. Once issued, select it from the Custom SSL certificate dropdown.
• Click Create distribution.

The distribution will take several minutes to deploy. Once its status is "Enabled," you can access your site via the provided distribution domain name (e.g., d123abcde.cloudfront.net).

4. Map a Custom Domain via Route 53 (Optional)

If you configured a custom domain (CNAME) in CloudFront, you must update your DNS records to point to the distribution.

• Navigate to the Route 53 console and select your domain's Hosted zone.
• Click Create record.
• Enter the subdomain (e.g., www) or leave it blank for the root domain.
• Set the Record type to A.
• Enable the Alias toggle.
• For Route traffic to, choose Alias to CloudFront distribution and select your distribution from the list.
• Click Create records.

DNS propagation may take some time. Once complete, your Gatsby site will be live on your custom domain, served securely and globally by CloudFront.

Conclusion

Using AWS S3 and CloudFront for a Gatsby website is a smart, cost-effective choice, as the generous free tiers for both services make it possible to host a small to medium-sized website for free.

• Amazon S3 (Simple Storage Service): Serves as your website's file storage. The "Always Free" tier includes 5 GB of standard storage, which is more than enough for most static Gatsby sites. This plan also provides ample GET and PUT requests for a typical website.
• Amazon CloudFront (CDN): Acts as a global delivery network, caching your S3 content at "edge locations" worldwide. This is the key to keeping costs down. The "Always Free" tier offers a massive 1 TB of data transfer out per month and 10,000,000 HTTP/S requests per month.

By using CloudFront, you benefit from a high cache-hit ratio, which means most user requests are served directly from the CDN's cache, not from S3. This significantly reduces your S3 data transfer and request costs, ensuring you stay well within the free limits. For most personal or small business websites, this combination provides a high-performance, serverless, and completely free hosting solution.