siddharth's space

If you’ve ever tried to migrate a site to S3 + CloudFront you know the documentation makes it look straightforward. It isn’t. This post covers the full setup end-to-end, including the subtle mistakes that will cost you hours if you don’t know about them.

The Architecture

Browser → CloudFront CDN → S3 (website endpoint)
             ↑
     ACM SSL Certificate

• S3 stores your static files
• CloudFront is the CDN — handles HTTPS, caching, and global edge delivery
• ACM provides the free SSL certificate
• Your registrar (Namecheap, GoDaddy, etc.) points DNS at CloudFront

For a proper www setup you actually need two S3 buckets and two CloudFront distributions — one to serve content, one to redirect the apex domain to www. There are two ways to reduce this overhead (see the alternatives in Step 1): skip the redirect S3 bucket using a CloudFront Function, or eliminate both the bucket and the apex distribution by delegating DNS to Cloudflare.

Step 1 — Create and Configure the S3 Buckets

Content bucket (www.yourdomain.com)

aws s3 mb s3://www.yourdomain.com --region us-east-1

# Disable the "Block Public Access" shield — required for website hosting
aws s3api put-public-access-block \
  --bucket www.yourdomain.com \
  --public-access-block-configuration \
  "BlockPublicAcls=false,IgnorePublicAcls=false,BlockPublicPolicy=false,RestrictPublicBuckets=false"

# Enable static website hosting
aws s3 website s3://www.yourdomain.com \
  --index-document index.html \
  --error-document index.html

# Allow public read
aws s3api put-bucket-policy --bucket www.yourdomain.com --policy '{
  "Version": "2012-10-17",
  "Statement": [{
    "Sid": "PublicRead",
    "Effect": "Allow",
    "Principal": "*",
    "Action": "s3:GetObject",
    "Resource": "arn:aws:s3:::www.yourdomain.com/*"
  }]
}'

Redirect bucket (yourdomain.com)

This bucket holds no content — it just redirects the apex domain to www. Configure it in the AWS Console: S3 → bucket → Properties → Static website hosting → Redirect requests → Host: www.yourdomain.com, Protocol: https.

Alternative 1 — Skip the redirect bucket with a CloudFront Function (stay in AWS)

The redirect bucket exists because https://yourdomain.com requires a TLS handshake before any redirect can happen — and the S3 redirect bucket itself can’t terminate TLS. CloudFront terminates TLS and then asks the origin what to do. But instead of asking S3, you can attach a CloudFront Function to the apex distribution that issues the 301 directly, before CloudFront ever contacts an origin. No redirect bucket needed.

You still need two CloudFront distributions (one per alternate domain name), but you can delete the S3 redirect bucket.

Steps:

1. In the CloudFront console, go to Functions → Create function. Give it a name (e.g. apex-redirect), select runtime cloudfront-js-2.0, and paste:

function handler(event) {
    return {
        statusCode: 301,
        statusDescription: 'Moved Permanently',
        headers: {
            location: { value: 'https://www.yourdomain.com' + event.request.uri }
        }
    };
}

2. Click Save, then Publish.
3. On the apex CloudFront distribution, go to Behaviors → Default (*) → Edit. Under Function associations → Viewer request, select your new function.
4. Save and deploy. The origin for the apex distribution is now irrelevant (the function returns before CloudFront contacts it), but CloudFront requires one — point it at www.yourdomain.com.s3-website-us-east-1.amazonaws.com as a harmless placeholder.
5. Delete the S3 redirect bucket.

CloudFront Function invocations cost $0.10 per million — effectively free for personal-site traffic.

Alternative 2 — Eliminate both the redirect bucket and the apex distribution with Cloudflare (free)

If you’d rather not manage any of this in AWS, Cloudflare’s free tier can handle the apex redirect entirely — no S3 bucket, no second CloudFront distribution. Cloudflare proxies yourdomain.com, terminates TLS using its Universal SSL certificate, and issues the 301 itself.

Here’s how:

1. Sign up at cloudflare.com and add your site. Cloudflare will import your existing DNS records.
2. At your registrar (e.g. Namecheap), change the nameservers to the two Cloudflare nameservers it gives you. Your domain stays registered at Namecheap — only DNS moves.
3. In the Cloudflare dashboard, go to Rules → Redirect Rules and create a rule:
   • When: Hostname equals yourdomain.com
   • Then: Static redirect → https://www.yourdomain.com (301)
4. Make sure the yourdomain.com DNS record (the @ / apex A or CNAME) has the Cloudflare proxy enabled (orange cloud icon). This is what lets Cloudflare terminate TLS for the apex domain using its Universal SSL certificate — no ACM cert needed for it.

With this setup you only need the single www S3 bucket, one CloudFront distribution, and one ACM certificate. The CNAME for www still points at CloudFront as before.

> Note: Cloudflare acts as a reverse proxy for the apex domain only long > enough to issue the redirect — the actual site content is still served by > your CloudFront distribution.

Step 2 — Request an SSL Certificate

Critical: the certificate must be in us-east-1 regardless of where your bucket lives. CloudFront only reads certificates from us-east-1.

aws acm request-certificate \
  --domain-name www.yourdomain.com \
  --subject-alternative-names yourdomain.com \
  --validation-method DNS \
  --region us-east-1

ACM will give you a CNAME record to add at your registrar for DNS validation. Add it and wait 5–10 minutes for status to change from PENDING_VALIDATION to ISSUED. Don’t proceed until it’s ISSUED — attaching a pending cert to CloudFront causes mysterious TLS errors later.

# Check status
aws acm list-certificates --region us-east-1 \
  --query "CertificateSummaryList[*].[DomainName,Status]" \
  --output table

> Tip: Request one certificate covering both www.yourdomain.com AND > yourdomain.com as a SAN. You can reuse it on both CloudFront distributions.

Step 3 — Create CloudFront Distributions

Create two distributions in the Console. For each:

Gotcha #1 — Always type the origin manually

When you click the Origin domain field, AWS presents a dropdown of your S3 buckets. Do not use it. The dropdown inserts the REST endpoint (www.yourdomain.com.s3.amazonaws.com). You want the website endpoint (www.yourdomain.com.s3-website-us-east-1.amazonaws.com). Type it manually.

Why it matters: The REST endpoint doesn’t serve directory index documents. So https://www.yourdomain.com/blog works but https://www.yourdomain.com/blog/ returns AccessDenied XML instead of blog/index.html. The website endpoint handles this correctly.

Gotcha #2 — The “add this domain later” warning

If your domain is registered outside Route 53 (e.g. Namecheap, GoDaddy), CloudFront will warn: “You need to add this domain later.” This is harmless — it just means CloudFront can’t auto-add the DNS record for you. Ignore it and proceed. You’ll add the CNAME manually in Step 4.

Gotcha #3 — Use TLSv1.2_2021

Higher versions might lead to handshake failures on some networks and corporate proxies. TLSv1.2_2021 is a safe version that works everywhere. That is what Cloudfront also recommends in the UI.

Step 4 — Upload Your Files

# Sync everything except build/config files
aws s3 sync . s3://www.yourdomain.com \
  --exclude "*.py" --exclude "*.pyc" \
  --exclude "*.yaml" --exclude "*.sh" \
  --exclude ".git/*" --exclude ".vscode/*"

# Fix Content-Type charset on all HTML files (see Gotcha #4 below)
aws s3 cp s3://www.yourdomain.com/ s3://www.yourdomain.com/ \
  --exclude "*" --include "*.html" \
  --no-guess-mime-type \
  --content-type "text/html; charset=utf-8" \
  --metadata-directive REPLACE \
  --recursive

Gotcha #4 — S3 serves HTML without charset, breaking Unicode

By default S3 serves HTML files with Content-Type: text/html — no charset. Browsers fall back to ISO-8859-1, which garbles any non-ASCII characters. The → arrow renders as â†'. Smart quotes, em-dashes, and emoji all break.

The fix is to explicitly set charset=utf-8 in the S3 object metadata, as shown in the sync script above. Note that having “ in your HTML is good practice but not sufficient — browsers prioritize the HTTP header over the meta tag.

Verify it worked:

aws s3api head-object \
  --bucket www.yourdomain.com \
  --key index.html \
  --query "ContentType"
# Should return: "text/html; charset=utf-8"

Step 5 — Update DNS at Your Registrar

Add these records (using Namecheap as an example):

> Note: Some registrars don’t allow CNAME at the apex (@). If yours doesn’t, > use their URL redirect feature to forward yourdomain.com → https://www.yourdomain.com, > or transfer DNS management to Route 53 which supports ALIAS records at the apex.

DNS propagation takes anywhere from 5 minutes to 48 hours depending on your registrar and TTL settings.

Step 6 — Ongoing Deploys

Save this as deploy.sh in your project root:

#!/bin/bash
set -eo pipefail

BUCKET="s3://www.yourdomain.com"
DIST_ID="YOUR_CLOUDFRONT_DISTRIBUTION_ID"

echo "Syncing files..."
aws s3 sync . "$BUCKET" \
  --exclude "*.py" --exclude "*.pyc" \
  --exclude "*.yaml" --exclude "*.sh" \
  --exclude ".git/*" --exclude ".vscode/*"

echo "Setting charset on HTML files..."
aws s3 cp "$BUCKET/" "$BUCKET/" \
  --exclude "*" --include "*.html" \
  --no-guess-mime-type \
  --content-type "text/html; charset=utf-8" \
  --metadata-directive REPLACE \
  --recursive

echo "Invalidating CloudFront cache..."
aws cloudfront create-invalidation \
  --distribution-id "$DIST_ID" \
  --paths "/*"

echo "Done."

> Tip: Always invalidate the CloudFront cache after deploying. Without it, > visitors may see the old version for up to 24 hours (the default TTL). The > invalidation is free for the first 1,000 paths per month.

Debugging Cheat Sheet

Cost

For a low-traffic personal or portfolio site:

• S3: < $0.01/month (storage + requests)
• CloudFront: free tier covers 1TB transfer + 10M requests/month
• ACM: free
• Route 53 (if used): $0.50/month per hosted zone

Total: effectively $0/month for personal sites.

Use PAYG pricing in CloudFront, not the Security Bundle (flat rate). The bundle includes AWS WAF and Shield Advanced — useful for high-traffic production apps, overkill (and expensive) for personal sites.

If you’re building a SaaS product on AWS Marketplace, there’s a subtle bug waiting for you in the subscription flow. It won’t show up in testing. It won’t throw an error. Your customer will just land on a broken page, and you’ll spend hours figuring out why.

I’ve shipped 4 SaaS products on AWS Marketplace. This race condition bit me on the first one. Here’s what it is and how to fix it.

How AWS Marketplace Subscription Works

When a customer subscribes to your SaaS product on AWS Marketplace, two things happen:

Flow A: The redirect. The customer clicks “Subscribe” and AWS sends them to your fulfillment URL with a registration token. You call ResolveCustomer to validate it, create a tenant record in your database, and redirect them to your signup page.

Flow B: The SQS notification. AWS also drops a subscribe-success message into your SQS queue. Your backend polls this queue and uses it to update the tenant’s subscription status.

Here’s the problem: these two flows are completely independent. AWS does not guarantee ordering between them.

The Race

The happy path looks like this:

1. Customer clicks Subscribe on AWS Marketplace
2. Customer is redirected to your /register endpoint
3. You call ResolveCustomer, create tenant row (status: subscribed)
4. Customer completes signup
   ... minutes later ...
5. SQS delivers subscribe-success
6. You UPDATE the tenant row -> status stays 'subscribed' (no-op)

Everything works. But here’s what actually happens sometimes:

1. Customer clicks Subscribe on AWS Marketplace
2. SQS delivers subscribe-success            <-- this arrives FIRST
3. You try to UPDATE the tenant row
4. ... but the row doesn't exist yet
5. UPDATE affects 0 rows. No error. Silent failure.
6. SQS message is deleted from the queue.    <-- it's gone now
   ... seconds later ...
7. Customer is redirected to your /register endpoint
8. You call ResolveCustomer, create tenant row
9. But you missed the subscribe-success event
10. What status do you set?

The SQS event arrived before your customer did. Your UPDATE hit nothing. The message was deleted from the queue. And now you have a customer with no subscription status, or worse, a customer stuck on a “subscription pending” screen forever.

This isn’t a theoretical edge case. It happens in production. The time between the customer clicking Subscribe and actually landing on your registration page can vary wildly – they might have a slow connection, they might get distracted, or your redirect might take a few seconds while SQS delivers in milliseconds.

The Wrong Fix

The obvious fix is: “Just don’t delete the SQS message if the tenant doesn’t exist yet. Let it retry.”

This is fragile. You’re now relying on SQS redelivery timing. If the customer takes 5 minutes to complete the redirect, you’re burning SQS visibility timeouts and retries. If they never complete registration, you have a poison message bouncing forever. And you’ve coupled your SQS processing to the state of a completely separate HTTP flow.

The Fix: Event Sourcing Lite

The solution is to decouple the two concerns:

1. Always persist the SQS event, regardless of whether the tenant exists.
2. Reconcile at registration time by reading the event history.

Here’s how it works in practice.

Step 1: Always save the event

When an SQS message arrives, write it to a subscription_events table first, unconditionally. Then attempt to update the tenant:

saveSubscriptionEvent(message) {
    const { action, customerIdentifier, productCode } = message;

    // Always write to the audit log -- this never fails
    db.subscriptionEvents.add(action, customerIdentifier, productCode, message);

    // Attempt to update the tenant (may not exist yet)
    if (action === 'subscribe-success') {
        const result = db.customers.updateSubscriptionStatus(
            customerIdentifier, 'subscribed'
        );
        if (result.changes === 0) {
            // Tenant hasn't registered yet. That's fine.
            // The event is safely persisted in subscription_events.
            logger.warn(
                `Customer ${customerIdentifier} not found in tenants table. ` +
                `Status will be reconciled at registration time.`
            );
        }
    }

    // Delete from SQS -- safe because the event is persisted locally
    this.deleteMessage(message);
}

The key insight: the subscription_events table is your durable log. It doesn’t depend on any other table existing. The SQS message can be safely deleted because the information has been transferred to your database.

Step 2: Reconcile at registration

When the customer finally hits /register, check the event history before creating the tenant:

// POST /register
app.post('/register', async (req, res) => {
    const { customerIdentifier, customerAWSAccountId } =
        await resolveCustomer(req.body.token);

    const existingTenant = db.customers.getByAwsAcctId(customerAWSAccountId);
    if (existingTenant) {
        // Returning customer -- redirect to login
        return res.redirect('/login');
    }

    // New customer -- check if SQS events arrived before they did
    const latestEvent = db.subscriptionEvents.getLatestByCustomer(
        customerIdentifier
    );
    const subscriptionStatus = latestEvent?.action === 'unsubscribe-success'
        ? 'unsubscribed'
        : 'subscribed';

    db.customers.add(
        customerAWSAccountId,
        customerIdentifier,
        offerType,
        subscriptionStatus  // <-- reconciled from event history
    );

    res.redirect('/signup');
});

The query is simple:

SELECT action, customer_identifier, created_at
FROM subscription_events
WHERE customer_identifier = ?
ORDER BY created_at DESC
LIMIT 1

If a subscribe-success event exists, the tenant is created as subscribed. If somehow an unsubscribe-success is the latest event, the tenant is created as unsubscribed. If no events exist yet (normal flow where the customer arrived before SQS), the default is subscribed – which is correct because ResolveCustomer itself validates that the subscription is active.

Why This Works

The subscription_events table acts as a write-ahead log. It decouples event persistence from tenant existence. No matter what order things happen:

Normal order (customer registers first):

/register creates tenant as 'subscribed' (default)
SQS arrives later, UPDATEs tenant -> no-op, already correct

Race condition (SQS arrives first):

SQS handler writes to subscription_events, UPDATE hits 0 rows -> that's fine
/register reads subscription_events, finds subscribe-success
Creates tenant as 'subscribed' -> correct

Edge case (unsubscribe before register):

SQS delivers unsubscribe-success, persisted to subscription_events
Customer visits /register
Latest event is unsubscribe-success -> tenant created as 'unsubscribed'
Access correctly denied

Every path converges to the correct state.

The Schema

You need one extra table:

CREATE TABLE subscription_events (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    action TEXT NOT NULL,
    customer_identifier TEXT NOT NULL,
    product_code TEXT NOT NULL,
    offer_identifier TEXT,
    raw_payload TEXT,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_subscription_events_customer
ON subscription_events(customer_identifier, created_at DESC);

The descending index on created_at makes the “get latest event” query fast. The raw_payload column stores the full SQS message body – useful for debugging and audit.

Bonus: You Get an Audit Trail for Free

This pattern gives you a complete history of every subscription lifecycle event. When a customer opens a support ticket saying “I subscribed but can’t access the product,” you can query:

SELECT action, created_at
FROM subscription_events
WHERE customer_identifier = 'cust-abc-123'
ORDER BY created_at DESC;

subscribe-success     2024-03-15 14:23:01
unsubscribe-pending   2024-03-15 14:22:58
subscribe-success     2024-01-10 09:15:33

You’ll know exactly what happened and when, without digging through CloudWatch logs.

Takeaway

The general pattern here is older than AWS: persist events before acting on them, and reconcile state from the event log. It’s event sourcing applied to a very specific problem, and it’s the simplest version of it – just one table, one query at registration time, and zero retry logic.

If you’re building an AWS Marketplace SaaS integration, save yourself the debugging session. Add the subscription_events table from day one.

I’ve packaged the production code behind this (and all the other AWS Marketplace plumbing – ResolveCustomer, auth, entitlements, metering) into a self-hosted Node.js gateway kit. If you’re listing a SaaS product on AWS Marketplace and don’t want to rebuild this from scratch, check it out here.

Are you building or listing a SaaS product on AWS Marketplace?

A pattern I’ve seen repeatedly: you end up rebuilding the same plumbing every time — customer onboarding, authentication, entitlement/subscription gating, and metering.

So I’m packaging my production code into a Node.js AWS Marketplace Authentication Gateway + Metering Kit (2-in-1). This is the same code I’ve used in production to ship 4 AWS Marketplace SaaS products.

What it is

• Self-hosted Node.js AWS Marketplace Authentication Gateway + Metering Kit (PAYG + Contract)

Who it’s for

• Teams building SaaS listings on AWS Marketplace who don’t want to rebuild ResolveCustomer/fulfillment, entitlement checks, subscription state, and metering semantics. This is one thing you don’t want to get wrong.

What it does

• ResolveCustomer + fulfillment onboarding
• Org admin panel (add /remove users)
• Gateway routing (authenticate incoming requests and forward to your upstream)
• Entitlement + PAYG subscription gating
• Metering endpoint (aggregation/dedupe/hourly semantics; monthly credits)

What it does NOT do

• SSO/OIDC (optional add-on)

How it’s delivered

• Private repo access + source included
• Runs in your VPC; no required third-party SaaS

Pricing

• $999 includes 12 months of updates
• White-glove installation and support available for extra

Get Started

• Get it here or contact to get a 4 page spec with more technical details.