Hosting Static Frontend on S3: A Developer's Guide

Previously in this course, we built the backend for our serverless application using API Gateway in Project Integration: Exposing the API with AWS CDK. In this lesson, we shift our focus to the client side, learning how to leverage S3 for Static Hosting to make your frontend assets globally accessible.

Understanding Static Hosting on S3

When you upload an HTML file to an S3 bucket, it's just an object in storage by default. To turn that storage bucket into a web server, you must explicitly enable Static Hosting.

When this feature is enabled, S3 provides a special website endpoint (e.g., my-bucket.s3-website-us-east-1.amazonaws.com). When a browser requests this URL, S3 acts as a web server: it interprets the request, looks for your index.html file, and returns it with the correct text/html content type.

Step 1: Enable Website Hosting

You can configure this via the AWS Console or the CLI. For now, we will use the console to understand the settings.

1. Navigate to the S3 service in your AWS console.
2. Select the bucket you created in Introduction to Amazon S3.
3. Click the Properties tab and scroll to the bottom.
4. Click Edit under Static website hosting.
5. Select Enable, set the Index document to index.html, and save.

Step 2: Upload Your Frontend Files

Once hosting is enabled, your bucket needs the actual files to serve. Since we are building a serverless web app, your frontend should be a collection of static files: index.html, style.css, and app.js.

Use the AWS CLI to sync your local build folder to the bucket:

Bash
# Ensure your current directory contains index.html
aws s3 sync ./dist s3://your-bucket-name

Step 3: Verify Site Access

By default, S3 buckets are private. If you try to visit your website endpoint now, you will receive a 403 Forbidden error. To allow the public to view your site, you must update the bucket policy—a concept we touched on in Managing S3 Bucket Policies.

Apply this policy to allow s3:GetObject for everyone:

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

Note: In production environments, it is standard practice to keep the bucket private and use CloudFront as an Origin Access Control (OAC) layer, which we will cover in the next lesson.

Hands-on Exercise

1. Create a simple index.html file on your machine with a "Hello World" heading.
2. Enable Static Website Hosting on a test S3 bucket as described above.
3. Upload the file and apply the bucket policy provided.
4. Navigate to the "Bucket website endpoint" listed in the Properties tab to verify your page loads in the browser.

Common Pitfalls

• Wrong Content-Type: If your browser downloads the index.html file instead of rendering it, check the metadata in S3. S3 usually detects the type correctly, but sometimes it defaults to binary/octet-stream.
• Case Sensitivity: Unlike local filesystems on some OSs, S3 keys are case-sensitive. Ensure your index.html filename matches your configuration exactly.
• Caching: S3 static hosting can be aggressive with caching. If you update your code but see the old version, clear your browser cache or perform a hard refresh.

FAQ

Can I use S3 to host a React or Vue application? Yes. You simply run your build process (e.g., npm run build), which generates static HTML, CSS, and JS files, and sync those to S3.

Is S3 Static Hosting secure? Hosting directly from S3 requires making the bucket public. For enhanced security, always front your S3 bucket with Amazon CloudFront, which allows you to keep the bucket private while serving content globally.

Recap

We've enabled Static Hosting on S3, uploaded our frontend assets, and configured the bucket policy to allow public read access. Your frontend is now live, serving as the interface for our serverless backend.

Up next: Configuring CloudFront for Security