AWS CloudFront Setup

This guide walks you through setting up AWS CloudFront as a reverse proxy so that requests to a specific folder on your domain (e.g., yoursite.com/lp/*) are forwarded to Flint, while all other traffic continues to reach your existing origin.

CloudFront uses origin groups and cache behaviors to route different URL paths to different backends. A CloudFront Function is used to rewrite the request path and set the correct forwarding headers before the request reaches Flint.

Estimated setup time: 30-60 minutes, depending on your existing CloudFront configuration.

Before you start, make sure you have:

• •An AWS account with permission to manage CloudFront distributions
• •Your existing CloudFront distribution (or one you are about to create)
• •Your Flint subdomain (e.g., yoursite.tryflint.com) - ask the Flint team if you are unsure
• •The folder path you want to use for Flint pages (we use /lp in all examples below)

When a visitor requests yoursite.com/lp/pricing, CloudFront matches the /lp/* cache behavior and:

1. 1.Invokes a CloudFront Function (viewer request) that rewrites the path and sets forwarding headers
2. 2.Forwards the request to your Flint subdomain as the origin
3. 3.Returns the Flint response to the visitor

The visitor's browser always shows your domain - they never see tryflint.com.

The CloudFront Function rewrites the incoming request path and adds the headers Flint needs to render pages correctly under your domain.

1. 1.In the AWS Console, go to CloudFront > Functions
2. 2.Click Create function
3. 3.Give it a name, e.g., flint-router
4. 4.Replace the default code with the following:

function handler(event) {
  var request = event.request;
  var uri = request.uri;
  var host = request.headers['host'].value;

  // Strip the /lp prefix so Flint receives the correct path
  if (uri.startsWith('/lp/')) {
    request.uri = uri.slice('/lp'.length);
  } else if (uri === '/lp') {
    request.uri = '/';
  }

  // Tell Flint which domain the visitor used
  request.headers['x-forwarded-host'] = { value: host };
  request.headers['x-forwarded-proto'] = { value: 'https' };

  return request;
}

5. 5.If your folder path is different from /lp, replace every occurrence of /lp in the function with your chosen path
6. 6.Click Save changes
7. 7.Click Publish function to make it available to your distribution

1. 1.In the AWS Console, go to CloudFront > Distributions and open your distribution
2. 2.Go to the Origins tab and click Create origin
3. 3.Configure the origin:
   • -Origin domain: Enter your Flint subdomain (e.g., yoursite.tryflint.com)
   • -Protocol: HTTPS only
   • -HTTPS port: 443
   • -Minimum origin SSL protocol: TLSv1.2
   • -Name: Give it a recognizable name, e.g., FlintOrigin
4. 4.Under Additional settings, set Origin custom headers:
   • -Header name: Host
   • -Value: Your Flint subdomain (e.g., yoursite.tryflint.com)
5. 5.Click Create origin

Important: Setting the Host header here ensures Flint can identify your site. Without it, Flint will not know which site's pages to serve.

Cache behaviors tell CloudFront which origin to use for a given path pattern.

1. 1.In your distribution, go to the Behaviors tab and click Create behavior
2. 2.Configure the behavior:
   • -Path pattern: /lp/* (or your chosen folder path followed by /*)
   • -Origin and origin groups: Select the FlintOrigin you created in Step 2
   • -Viewer protocol policy: Redirect HTTP to HTTPS
   • -Allowed HTTP methods: GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE
   • -Cache policy: Select CachingDisabled (or create a minimal-TTL policy - Flint manages its own caching)
   • -Origin request policy: Select AllViewerExceptHostHeader (CloudFront's managed policy) to forward query strings and cookies
3. 3.Under Function associations, find the Viewer request event and:
   • -Select CloudFront Functions as the function type
   • -Select the flint-router function you published in Step 1
4. 4.Click Create behavior

Note: CloudFront evaluates behaviors in order from most specific to least specific. The new /lp/* behavior will be matched before your default /* behavior, so your existing site is unaffected.

If you want yoursite.com/lp (without a trailing slash) to also work, add a second behavior:

1. 1.Create another behavior with path pattern /lp (no wildcard)
2. 2.Use the same origin (FlintOrigin) and the same CloudFront Function association
3. 3.Set the same cache and origin request policies

Alternatively, you can handle this redirect inside the CloudFront Function itself by returning a 301 response when uri === '/lp':

if (uri === '/lp') {
  return {
    statusCode: 301,
    statusDescription: 'Moved Permanently',
    headers: {
      location: { value: '/lp/' }
    }
  };
}

After saving the new behavior, CloudFront will begin deploying the change to all edge locations. This usually takes 2-5 minutes.

If you previously cached any /lp/* paths (unlikely if you just added the path, but possible), create a cache invalidation:

1. 1.Go to the Invalidations tab in your distribution
2. 2.Click Create invalidation
3. 3.Enter /lp/* in the object paths
4. 4.Click Create invalidation

Once the distribution status shows Deployed:

1. 1.Visit yoursite.com/lp - you should see your Flint content
2. 2.Visit yoursite.com - your regular site should be unaffected
3. 3.Check that the browser address bar shows your domain throughout

If you see a CloudFront error page, wait 2-3 more minutes for the deployment to fully propagate and try again.

If your CloudFront distribution already serves a custom domain (e.g., yoursite.com) with an ACM certificate, no additional certificate changes are needed - the new behavior inherits the same domain and TLS configuration.

If you are setting up a new distribution:

1. 1.Request a certificate in AWS Certificate Manager (ACM) in the us-east-1 region (required for CloudFront)
2. 2.Validate the certificate via DNS
3. 3.Attach the certificate to your distribution under Settings > Custom SSL certificate
4. 4.Add your domain under Alternate domain names (CNAMEs)
5. 5.Update your DNS to point your domain to the CloudFront distribution domain (e.g., d1234abcd.cloudfront.net) using a CNAME or ALIAS record

My Flint pages return a 403 or 502 error

• •Confirm the Host custom header on the Flint origin is set to your Flint subdomain exactly as provided by the Flint team.
• •Make sure the CloudFront Function is published (not just saved). Unpublished functions are not applied to live traffic.
• •Check that the Function is associated with the Viewer request event on the correct behavior, not on the default behavior.

My existing site is broken after adding the behavior

• •Verify the path pattern is /lp/* and not /*. The default /* behavior should still point to your original origin.
• •Check the behavior order in the Behaviors tab - the new /lp/* behavior should be listed above the default /* behavior.

CloudFront returns the wrong content or shows Flint on all pages

• •The path pattern may be too broad. Ensure it is /lp/* and not * or /*.

Pages load but assets (CSS/JS) are missing

• •Make sure the origin request policy forwards query strings. Select AllViewerExceptHostHeader or create a custom policy that includes query string forwarding.

The URL shows tryflint.com instead of my domain

• •Ensure the CloudFront Function sets x-forwarded-host to the incoming host header value, and that the function is published and associated with the correct behavior.

Cache invalidation is not working

• •Invalidations can take several minutes. If pages still appear stale, check that the cache behavior's Cache policy is not set to a long TTL. Use CachingDisabled during initial testing.

If you run into issues during setup or are unsure of any values (such as your Flint subdomain), reach out to the Flint team and we'll help you get set up.