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) - this is configured in the Settings modal inside the Flint app, or the Flint team can set it up for you
• •The folder path you want to use for Flint pages (we use /use-cases in all examples below, but any path works)

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

1. 1.Forwards the request to your Flint subdomain as the origin, preserving the full path
2. 2.Returns the Flint response to the visitor

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

Important: If you are pointing a subpath (e.g., /use-cases/*) to a Flint site that is also hosted under that same subpath, you do not need to strip the path prefix - Flint handles it as-is. A CloudFront Function that strips the prefix will cause the wrong path to be requested on the Flint origin and result in 404 errors.

A CloudFront Function is only needed if you want Flint to receive a different path than what the visitor requested - for example, if you want yoursite.com/use-cases/* to map to yoursite.tryflint.com/ (root). In most cases, you do not need a function - skip this step unless you specifically need path rewriting.

Why you might skip this step: If your Flint pages are published under the same subpath (e.g., /use-cases/* on Flint matches /use-cases/* on your domain), CloudFront can forward requests directly to Flint without any path modification. Adding a function that strips the prefix will cause 404 errors on the Flint origin.

If you do need path rewriting, create a function that only sets x-forwarded-host - do not set x-forwarded-proto, as it is a forbidden header that causes CloudFront to return a 502 error:

1. 1.In the AWS Console, go to CloudFront > Functions
2. 2.Click Create function and give it a name, e.g., flint-router
3. 3.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 /use-cases prefix so Flint receives the path from root
  // Only add this if your Flint pages are published at the root path
  if (uri.startsWith('/use-cases/')) {
    request.uri = uri.slice('/use-cases'.length);
  } else if (uri === '/use-cases') {
    request.uri = '/';
  }

  // Tell Flint which domain the visitor used
  // Do NOT set x-forwarded-proto - it is a forbidden header and causes 502 errors
  request.headers['x-forwarded-host'] = { value: host };

  return request;
}

4. 4.Replace /use-cases with your chosen path if different
5. 5.Click Save changes, then Publish function

Your Flint subdomain (e.g., yoursite.tryflint.com) is configured through the Settings modal in the Flint app. If you have not set one up yet, contact the Flint team.

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. You need to create two behaviors: one for your page path, and one for Flint's asset path (/flint-assets/*). Without the second behavior, page assets such as images, CSS, and JavaScript will fail to load.

Behavior 1 - Your page path (e.g., /use-cases/*):

1. 1.In your distribution, go to the Behaviors tab and click Create behavior
2. 2.Configure the behavior:
   • -Path pattern: /use-cases/* (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 (Flint manages its own caching)
   • -Origin request policy: Select AllViewerExceptHostHeader (CloudFront's managed policy) to forward query strings and cookies
3. 3.If you need path rewriting (see Step 1), under Function associations set the Viewer request event to the flint-router function. Otherwise, leave function associations empty.
4. 4.Click Create behavior

Behavior 2 - Flint assets (/flint-assets/*):

Flint serves its page assets (images, CSS, JS) from the /flint-assets/ subpath. You must add a matching behavior that routes this path to the same Flint origin, or assets will be missing on your pages.

1. 1.Click Create behavior again
2. 2.Configure the behavior:
   • -Path pattern: /flint-assets/*
   • -Origin and origin groups: Select the same FlintOrigin
   • -Viewer protocol policy: Redirect HTTP to HTTPS
   • -Allowed HTTP methods: GET, HEAD
   • -Cache policy: Select CachingDisabled
   • -Origin request policy: Select AllViewerExceptHostHeader
3. 3.Leave function associations empty for this behavior
4. 4.Click Create behavior

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

If you want yoursite.com/use-cases (without a trailing slash) to also work, add another behavior:

1. 1.Create another behavior with path pattern /use-cases (no wildcard)
2. 2.Use the same origin (FlintOrigin) and the same settings as Behavior 1

Alternatively, you can handle this redirect inside a CloudFront Function by returning a 301 response when uri === '/use-cases':

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

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

If you previously cached any paths (unlikely if you just added them, but possible), create a cache invalidation:

1. 1.Go to the Invalidations tab in your distribution
2. 2.Click Create invalidation
3. 3.Enter /use-cases/* and /flint-assets/* in the object paths
4. 4.Click Create invalidation

Once the distribution status shows Deployed:

1. 1.Visit yoursite.com/use-cases - 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
4. 4.Confirm images and other assets on the page load correctly

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 502 error

• •If you have a CloudFront Function associated with the behavior, check whether it sets x-forwarded-proto. This is a forbidden header that CloudFront will reject, causing a 502. Remove that line from the function.
• •Confirm the Host custom header on the Flint origin is set to your Flint subdomain.
• •As a diagnostic step, try temporarily removing the function association entirely - if pages load after that, the function is the cause.

My Flint pages return a 404 error

• •If you have a CloudFront Function that strips a path prefix (e.g., /use-cases), confirm that your Flint pages are actually published at the resulting path. If your Flint pages are published under /use-cases/*, the function should not strip that prefix - Flint expects to receive the full path.
• •Confirm the Host custom header on the Flint origin is set to your Flint subdomain exactly.

My Flint pages return a 403 error

• •Make sure the CloudFront Function is published (not just saved). Unpublished functions are not applied to live traffic.
• •Check that any 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 /use-cases/* and not /*. The default /* behavior should still point to your original origin.
• •Check the behavior order in the Behaviors tab - the new behaviors 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 matches only your intended subpath and is not * or /*.

Pages load but images or other assets are missing

• •You likely need a separate behavior for /flint-assets/* pointing to the same Flint origin. Flint serves page assets from this subpath, and without a matching behavior, CloudFront will route those requests to your existing origin instead. See Step 3 for setup instructions.
• •Also confirm 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.

I do not know my Flint subdomain

• •Your .tryflint.com subdomain is configured in the Settings modal inside the Flint app. If you have not set one up yet, contact the Flint team.

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.