AWS Route 53 and Cloudfront

Host documentation at a /docs subdirectory using AWS services

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

Ensure that CloudFront forwards the HOST header and client IP information correctly. This is critical for Vercel’s verification processes.

When using CloudFront with Vercel deployments, CloudFront automatically adds the CloudFront-Viewer-Address header containing the original client’s IP address.

Make sure your CloudFront distribution is configured to forward this header to your origin by including it in your origin request policy or cache policy headers configuration.

Create Cloudfront Distribution

Navigate to Cloudfront inside the AWS console and click on Create distribution

For the Origin domain, input [SUBDOMAIN].mintlify.dev where [SUBDOMAIN] is the project’s unique subdomain. Click on Use: [SUBDOMAIN].mintlify.dev

For Cache key and origin requests, select Caching Optimized.

And for Web Application Firewall (WAF), enable security protections

The remaining settings should be default. Click Create distribution.

Add Default Origin

After creating the distribution, navigate to the Origins tab.

We want to find a staging URL that mirrors where the main domain (example.com). This is highly variant depending on how your landing page is hosted.

For instance, if your landing page is hosted on Webflow, you can use the Webflow’s staging URL. It would look like .webflow.io.

If you use Vercel, you use the .vercel.app domain available for every project.

If you’re unsure on how to get a staging URL for your landing page, contact support and we’d be happy to help

Once you have the staging URL, ours for instance is mintlify-landing-page.vercel.app, create a new Origin and add it as the Origin domain.

By this point, you should have two Origins - one with [SUBDOMAIN].mintlify.app and another with with staging URL.

Set Behaviors

Behaviors in Cloudfront enables 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

Select the Create behavior button and create the following behaviors.

/.well-known/*

If you are deploying to Vercel, create a behavior for Vercel verification paths with a Path pattern of /.well-known/* and Origin and origin groups pointing to your main origin (the staging URL).

For Cache policy, select CachingDisabled to ensure these verification requests pass through without caching.

/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)

For Cache policy, select CachingOptimized and create behavior.

/docs

Create a behavior with a Path pattern of /docs and Origin and origin groups pointing to the same .mintlify.dev URL.

Default (*)

Lastly, we’re going to edit the Default (*) behavior.

We’re going to change the default behavior’s Origin and origin groups to the staging URL (in our case mintlify-landing-page.vercel.app).

Click on Save changes.

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.

All pages should be directing to your main landing page, but if you append /docs to the URL, you should see it going to the Mintlify documentation instance.

Connecting it 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

Navigate to Route53 inside the AWS console, and click into the Hosted zone for your primary domain. Click on Create record

Toggle Alias and then Route traffic to the Alias to CloudFront distribution option.

Click Create records.

You may need to remove the existing A record if one currently exists.

And voila! Your documentation will be served 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.