Host a Static Website on AWS S3 in Minutes

tName: props.domainName, versioned: true, // Block public ACLs to enforce policy-based access blockPublicAccess: s3.BlockPublicAccess.BLOCK_ACLS, // Configure native website hosting features websiteIndexDocument: props.indexDocument, websiteErrorDocument: props.errorDocument, // Enable encryption at rest encryption: s3.BucketEncryption.S3_MANAGED, });

// Attach resource policy for public read access
this.bucket.addToResourcePolicy(new iam.PolicyStatement({
  sid: 'AllowPublicRead',
  effect: cdk.aws_iam.Effect.ALLOW,
  principals: [new iam.AnyPrincipal()],
  actions: ['s3:GetObject'],
  resources: [this.bucket.arnForObjects('*')],
}));

// Output the website endpoint for verification
new cdk.CfnOutput(this, 'WebsiteEndpoint', {
  value: this.bucket.bucketWebsiteUrl,
  description: 'S3 Website Endpoint URL',
});

} }

#### Rationale

*   **`blockPublicAccess.BLOCK_ACLS`**: This setting prevents the use of legacy ACLs, forcing all access control through the bucket policy. This reduces the attack surface and aligns with AWS security recommendations.
*   **`websiteIndexDocument` / `websiteErrorDocument`**: These properties configure the bucket to behave like a web server, serving the specified files when a directory is requested or an error occurs.
*   **`S3_MANAGED` Encryption**: Ensures all objects are encrypted at rest without managing keys, providing a baseline security requirement at no extra cost.
*   **Policy Scope**: The policy grants `s3:GetObject` to `*`. This is safe for public assets. Write operations are restricted to IAM roles with explicit `s3:PutObject` permissions, preventing unauthorized uploads.

### Pitfall Guide

Production deployments often fail due to subtle configuration errors. The following pitfalls address common mistakes observed in real-world implementations.

| Pitfall Name | Explanation | Fix |
| :--- | :--- | :--- |
| **The HTTPS Illusion** | Developers assume S3 supports HTTPS on the website endpoint. It does not. The endpoint is HTTP-only. | Deploy CloudFront in front of the bucket. Configure the distribution to use the S3 origin and enable HTTPS viewer protocol policy. |
| **Route 53 Alias Mismatch** | Route 53 alias records pointing to S3 require the bucket name to match the domain exactly. A mismatch causes DNS resolution failure. | Ensure the S3 bucket name is identical to the domain (e.g., `www.example.com` bucket for `www.example.com` domain). |
| **Stale Asset Delivery** | Failing to set `Cache-Control` headers results in browsers re-fetching assets on every visit, increasing latency and S3 costs. | Set `Cache-Control: max-age=31536000, immutable` on hashed assets during upload. Use shorter TTLs for `index.html`. |
| **Case-Sensitive Routing** | S3 object keys are case-sensitive. Requesting `/About` when the file is `about.html` returns a 404. | Enforce lowercase naming conventions in your build pipeline. Configure the error document to handle client-side routing fallbacks. |
| **CORS Configuration Gaps** | Static sites making API calls to different domains fail without proper Cross-Origin Resource Sharing headers. | Add a CORS configuration to the bucket allowing `GET` requests from your domain. Use `AllowedOrigins` and `AllowedHeaders`. |
| **Security Headers Absence** | S3 does not inject security headers like `X-Frame-Options` or `Content-Security-Policy`. | Use CloudFront Functions or Lambda@Edge to inject security headers into responses before they reach the client. |
| **Cost Leakage via Requests** | High traffic to uncacheable content generates excessive S3 GET requests, which are billed per request. | Ensure CloudFront caching is effective. Set appropriate TTLs. Monitor `4xxErrorRate` and `5xxErrorRate` metrics to detect misconfigurations. |

### Production Bundle

#### Action Checklist

- [ ] **Provision Bucket**: Create S3 bucket with versioning enabled and name matching target domain.
- [ ] **Apply Policy**: Attach bucket policy allowing `s3:GetObject` for public read access.
- [ ] **Configure Hosting**: Set index and error documents in bucket properties.
- [ ] **Deploy CDN**: Create CloudFront distribution pointing to S3 origin; enable HTTPS and security headers.
- [ ] **Set Cache Headers**: Configure upload scripts to apply `Cache-Control` metadata based on file type.
- [ ] **Route DNS**: Create Route 53 Alias record pointing to CloudFront distribution.
- [ ] **Validate**: Test HTTP/HTTPS endpoints, verify 404 handling, and check cache hit ratios.

#### Decision Matrix

| Scenario | Recommended Approach | Why | Cost Impact |
| :--- | :--- | :--- | :--- |
| **Internal Dev/Test** | S3 Website Endpoint Only | Rapid deployment; HTTPS not required for internal tools. | Lowest. Pay only for storage and requests. |
| **Public Production** | S3 + CloudFront | Mandatory HTTPS; global performance; reduced S3 costs via caching. | Moderate. CDN adds cost but saves on S3 requests. |
| **SPA with Client Routing** | S3 + CloudFront + Lambda@Edge | CloudFront can intercept 404s and serve `index.html` for client-side routers. | Higher. Lambda@Edge execution costs apply. |
| **High-Security App** | S3 + CloudFront + OAI + WAF | Origin Access Identity restricts direct S3 access; WAF blocks malicious traffic. | Higher. WAF rules and OAI add complexity/cost. |

#### Configuration Template

Use this AWS CLI command to sync your build artifacts with optimized cache control. This template excludes HTML files from long-term caching while maximizing cache duration for static assets.

```bash
# Sync distribution folder to S3 with cache control strategies
aws s3 sync ./dist s3://prod-assets-codcompass.io \
  --delete \
  --cache-control "max-age=0, must-revalidate" \
  --exclude "*.html" \
  --exclude "*.json" \
  --exclude "sitemap.xml" \
  --exclude "robots.txt"

# Apply long-term caching to hashed assets
aws s3 sync ./dist s3://prod-assets-codcompass.io \
  --cache-control "max-age=31536000, public, immutable" \
  --include "*.js" \
  --include "*.css" \
  --include "*.png" \
  --include "*.jpg" \
  --include "*.svg" \
  --include "*.woff2"

Quick Start Guide

1. Initialize Infrastructure: Run cdk deploy with the provided construct to provision the bucket and policy.
2. Upload Assets: Execute the aws s3 sync commands from the configuration template to upload your build output.
3. Verify Endpoint: Access the WebsiteEndpoint output from the CDK deployment to confirm the site loads over HTTP.
4. Enable HTTPS: Create a CloudFront distribution with the S3 bucket as the origin. Update DNS to point to the CloudFront domain.
5. Monitor: Check CloudWatch metrics for 4xxErrorRate and 5xxErrorRate to ensure healthy operation.