To host your documentation at a /docs subpath using AWS Route 53 and CloudFront, you need to configure your DNS provider to point to your CloudFront distribution.

Proxies with Vercel deployments

If you use AWS CloudFront as a proxy with Vercel deployments, you must configure CloudFront to avoid interfering with Vercel’s domain verification and SSL certificate provisioning. Improper CloudFront configuration can prevent Vercel from provisioning Let’s Encrypt SSL certificates and cause domain verification failures.

Required path allowlist

CloudFront must allow traffic to these specific paths without caching or blocking:
  • /.well-known/acme-challenge/* - Required for Let’s Encrypt certificate verification
  • /.well-known/vercel/* - Required for Vercel domain verification
These paths should be configured to bypass CloudFront caching and pass through directly to your origin.

Header forwarding requirements

You must create a custom origin request policy that forwards the HOST header and client IP information correctly. This is critical for Vercel’s verification processes.
  1. Create a custom origin request policy named VercelCloudFrontProxy.
  2. Include the Origin and CloudFront-Viewer-Address headers.
You must include the CloudFront-Viewer-Address header in your origin request policy or cache policy headers configuration to forward the header to your origin.

Create CloudFront distribution

  1. Navigate to CloudFront inside the AWS console.
  2. Select Create distribution.
CloudFront Distributions page with the "Create distribution" button emphasized.
  1. For the Origin domain, input [SUBDOMAIN].mintlify.dev where [SUBDOMAIN] is your project’s unique subdomain.
CloudFront "Create distribution" page showing "acme.mintlify.dev" as the origin domain.
  1. For “Web Application Firewall (WAF),” enable security protections.
Web Application Firewall (WAF) options with "Enable security protections" selected.
  1. The remaining settings should be default.
  2. Select Create distribution.

Add default origin

  1. After creating the distribution, navigate to the “Origins” tab.
A CloudFront distribution with the "Origins" tab highlighted.
  1. Find your staging URL that mirrors the main domain. This is highly variant depending on how your landing page is hosted. For example, the Mintlify staging URL is mintlify-landing-page.vercel.app.
If your landing page is hosted on Webflow, use Webflow’s staging URL. It would look like .webflow.io.If you use Vercel, use the .vercel.app domain available for every project.
  1. Create a new Origin and add your staging URL as the “Origin domain”.
CloudFront "Create origin" page with a "Origin domain" input field highlighted.
By this point, you should have two Origins: one with [SUBDOMAIN].mintlify.app and another with your staging URL.
CloudFront "Origins" page with two origins: One for mintlify and another for mintlify-landing-page.

Set behaviors

Behaviors in CloudFront enable control over the subpath logic. At a high level, we’re looking to create the following logic.
  • If a user lands on /docs, go to [SUBDOMAIN].mintlify.dev.
  • If a user lands on any other page, go the current landing page.
  1. Navigate to the “Behaviors” tab of your CloudFront distribution.
CloudFront "Behaviors" tab highlighted.
  1. Select the Create behavior button and create the following behaviors.

/.well-known/*

Create behaviors for Vercel domain verification paths with a Path pattern of /.well-known/* and set Origin and origin groups to your docs URL. For “Cache policy”, select CachingDisabled to ensure these verification requests pass through without caching.
CloudFront "Create behavior" page with a "Path pattern" of "/.well-known/*" and "Origin and origin groups" pointing to the staging URL.
If .well-known/* is too generic, it can be narrowed down to 2 behaviors at a minimum for Vercel:
  • /.well-known/vercel/* - Required for Vercel domain verification
  • /.well-known/acme-challenge/* - Required for Let’s Encrypt certificate verification

/docs

Create a behavior with a Path pattern of /docs with Origin and origin groups pointing to the .mintlify.dev URL (in our case acme.mintlify.dev).
  • Set “Cache policy” to CachingOptimized.
  • In “Origin request policy”, create an origin request policy named VercelCloudFrontProxy. That forwards the Origin and CloudFront-Viewer-Address headers.
CloudFront Create origin request policy page that forwards the Origin and CloudFront-Viewer-Address headers
  • Set Viewer Protocol Policy to Redirect HTTP to HTTPS
CloudFront "Create behavior" page with a "Path pattern" of "/docs/*" and "Origin and origin groups" pointing to the acme.mintlify.dev URL.

/docs/*

Create a behavior with a Path pattern of /docs/* and Origin and origin groups pointing to the same .mintlify.dev URL. These settings should exactly match /docs. With the exception of the Path pattern.
  • Set “Cache policy” to CachingOptimized.
  • Set “Origin request policy” to VercelCloudFrontProxy.
  • Set “Viewer protocol policy” to Redirect HTTP to HTTPS

Default (*)

Lastly, we’re going to edit the Default (*) behavior.
A CloudFront distribution with the "Default (*)" behavior selected and the Edit button emphasized.
  1. Change the default behavior’s Origin and origin groups to the staging URL (in our case mintlify-landing-page.vercel.app).
CloudFront "Edit behavior" page with the "Origin and origin groups" input field highlighted.
  1. Select Save changes.

Check behaviors are set up correctly

If you follow the above steps, your behaviors should look like this:
CloudFront "Behaviors" page with 4 behaviors: /docs/*, /docs, Default, and /.well-known/*.

Preview distribution

You can now test if your distribution is set up properly by going to the “General” tab and visiting the Distribution domain name URL.
CloudFront "General" tab with the "Distribution domain name" URL highlighted.
All pages should be directing to your main landing page, but if you append /docs to the URL, you should see it going to your Mintlify documentation instance.

Connect with Route53

Now, we’re going to bring the functionality of the CloudFront distribution into your primary domain.
For this section, you can also refer to AWS’s official guide on Configuring Amazon Route 53 to route traffic to a CloudFront distribution
  1. Navigate to Route53 inside the AWS console.
  2. Navigate to the “Hosted zone” for your primary domain.
  3. Select Create record.
Route 53 "Records" page with the "Create record" button emphasized.
  1. Toggle Alias and then Route traffic to the Alias to CloudFront distribution option.
Route 53 "Create record" page with the "Alias" toggle and the "Route traffic to" menu highlighted.
  1. Select Create records.
You may need to remove the existing A record if one currently exists.
Your documentation is now live at /docs for your primary domain.
After configuring your DNS, custom subdomains are usually available within a few minutes. DNS propagation can sometimes take 1-4 hours, and in rare cases up to 48 hours. If your subdomain is not immediately available, please wait before troubleshooting.