Hosting Static Websites on AWS S3 with CloudFront: A Comprehensive Guide

TL;DR

This guide provides a detailed walkthrough for hosting static websites on AWS S3, leveraging CloudFront for global content delivery, HTTPS, custom domains, and performance optimization. It covers S3 bucket configuration, content uploading, CloudFront distribution setup, Route 53 DNS management, security best practices, cost considerations, and common troubleshooting scenarios. The recommended architecture prioritizes scalability, security, and cost-efficiency for modern static web applications.

Introduction

This document outlines the process of deploying and managing a static website using Amazon S3 for storage and CloudFront as a Content Delivery Network (CDN). This approach offers significant advantages in terms of availability, scalability, performance, and cost-effectiveness compared to traditional web hosting methods. We will cover the entire lifecycle, from initial setup to advanced configurations and ongoing maintenance.

Prerequisites

Essential AWS Services and Tools

index.html

or equivalent | Required for S3 static website hosting | | Error Document |

error.html

or equivalent | For handling 404s and other errors |

Website Assets Preparation

1. S3 Bucket Setup for Static Website Hosting

This section details the creation and configuration of an S3 bucket to serve static website content.

Creating an S3 Bucket

AWS CLI:

aws s3api create-bucket \
    --bucket your-unique-website-bucket-name \
    --region us-east-1 \
    --create-bucket-configuration LocationConstraint=us-east-1 # Omit for us-east-1

AWS Management Console: Navigate to S3, click "Create bucket," provide a globally unique name, select a region, and choose to block all public access (this will be reconfigured via bucket policy for website hosting).

Enabling Static Website Hosting

Configure the bucket to serve files as a website.

AWS CLI:

aws s3api put-bucket-website \
    --bucket your-unique-website-bucket-name \
    --website-configuration '{
        "IndexDocument": {"Suffix": "index.html"},
        "ErrorDocument": {"Key": "error.html"}
    }'

AWS Management Console: In the bucket's properties, find "Static website hosting," enable it, specify

index.html

as the Index document, and

error.html

as the Error document. Note the Endpoint URL provided by S3; this is crucial for initial testing but will be superseded by CloudFront.

Bucket Policy for Public Read Access

To allow unauthenticated access to your website files, apply a bucket policy.

AWS CLI:

aws s3api put-bucket-policy \
    --bucket your-unique-website-bucket-name \
    --policy '{
        "Version": "2012-10-17",
        "Statement": [
            {
                "Sid": "PublicReadGetObject",
                "Effect": "Allow",
                "Principal": "*",
                "Action": "s3:GetObject",
                "Resource": "arn:aws:s3:::your-unique-website-bucket-name/*"
            }
        ]
    }'

Important: This policy makes objects publicly readable. For production environments using CloudFront, it's recommended to restrict direct S3 access and use CloudFront Origin Access Identity (OAI) or Origin Access Control (OAC) for more secure access. This public policy is for simplicity in the initial S3 website endpoint testing phase.

CORS Configuration (If Required)

If your website needs to access resources from different domains (e.g., APIs), configure Cross-Origin Resource Sharing (CORS).

AWS CLI:

aws s3api put-bucket-cors \
    --bucket your-unique-website-bucket-name \
    --cors-configuration '{
        "CORSRules": [
            {
                "AllowedOrigins": ["http://localhost:3000", "https://your-domain.com"],
                "AllowedMethods": ["GET"],
                "MaxAgeSeconds": 3000,
                "AllowedHeaders": ["*"]
            }
        ]
    }'

Note: Adjust

AllowedOrigins

and

AllowedMethods

to your specific security requirements.

2. Uploading Website Content

Transfer your static assets to the configured S3 bucket.

File Organization Strategy

A typical project structure:

your-website-root/
├── index.html
├── error.html
├── assets/
│   ├── css/
│   │   └── styles.min.css
│   ├── js/
│   │   └── main.bundle.js
│   └── images/
│       └── logo.webp
├── about/
│   └── index.html # Accessible at /about/
└── contact/
    └── index.html # Accessible at /contact/

Key Principle: S3 treats objects as files. The directory structure in your upload maps directly to URL paths. For example,

about/index.html

becomes accessible at

your-bucket-url/about/

Uploading Files with AWS CLI

The

aws s3 sync

command is efficient for uploading. It synchronizes the local directory with the S3 bucket, uploading only new or modified files.

# Navigate to your website's root directory in the terminal
cd your-website-root/

aws s3 sync . s3://your-unique-website-bucket-name \
    --acl public-read \ # If using S3 website endpoint directly (not recommended with CloudFront OAC/OAI)
    --exclude "*.DS_Store" \
    --exclude "node_modules/*" \
    --cache-control "max-age=3600" \ # Default cache for most files
    --content-type "text/html" --exclude "*" --include "*.html" \
    --content-type "text/css" --exclude "*" --include "*.css" \
    --content-type "application/javascript" --exclude "*" --include "*.js" \
    --content-type "image/webp" --exclude "*" --include "*.webp" \
    --content-type "image/jpeg" --exclude "*" --include "*.jpg" --include "*.jpeg" \
    --content-type "image/png" --exclude "*" --include "*.png"

Explanation of Flags:

.
: Sync from the current local directory.
s3://your-unique-website-bucket-name
: The target S3 bucket.
--acl public-read
: Grants public read access to uploaded objects. Deprecated in favor of bucket policies and CloudFront OAC/OAI.
--exclude
/
--include
: Fine-tune which files are uploaded.
--cache-control
: Sets the
Cache-Control
HTTP header. Essential for performance.
--content-type
: Explicitly sets the
Content-Type
header, crucial for browsers to render files correctly. Multiple
--include
and
--content-type
pairs are used to apply specific types.

Note on

public-read

ACL: While common for direct S3 website hosting, it's generally discouraged when using CloudFront. CloudFront's Origin Access Control (OAC) or Origin Access Identity (OAI) allows CloudFront to access S3 objects privately, enhancing security. The bucket policy should be adjusted to grant

GetObject

permissions to the OAI/OAC principal.

Content Type and Cache-Control Best Practices

| File Extension |

Content-Type

Header |

Cache-Control

Header | Notes | | :------------- | :---------------------------- | :------------------------------------ | :---------------------------------------- | |

.html

text/html

no-cache, max-age=0

| Revalidate frequently to ensure freshness | |

.css

text/css

public, max-age=604800, immutable

| Cache for 1 week,

immutable

for cache busting | |

.js

application/javascript

public, max-age=604800, immutable

| Cache for 1 week,

immutable

for cache busting | |

.jpg

.jpeg

image/jpeg