AWS Route 53 and CloudFront

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.

​

High-level overview

Route traffic to these paths with a Cache Policy of CachingDisabled:

• /.well-known/acme-challenge/* - Required for Let’s Encrypt certificate verification
• /.well-known/vercel/* - Required for domain verification
• /docs/* - Required for subpath routing
• /docs/ - Required for subpath routing

Route traffic to this path with a Cache Policy of CachingEnabled:

• /mintlify-assets/_next/static/*
• Default (*) - Your websites landing page

All Behaviors must have the an origin request policy of AllViewerExceptHostHeader.

​

Create CloudFront distribution

1. Navigate to CloudFront inside the AWS console.
2. Select Create distribution.

3. For the Origin domain, input [SUBDOMAIN].mintlify.dev where [SUBDOMAIN] is your project’s unique subdomain.

4. For “Web Application Firewall (WAF),” enable security protections.

5. The remaining settings should be default.
6. Select Create distribution.

​

Add default origin

1. After creating the distribution, navigate to the “Origins” tab.

2. 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.

3. Create a new Origin and add your staging URL as the “Origin domain”.

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

​

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.

2. 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.

​

/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.
• Set “Origin request policy” to AllViewerExceptHostHeader.
• Set Viewer Protocol Policy to Redirect HTTP to HTTPS

​

/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 AllViewerExceptHostHeader.
• Set “Viewer protocol policy” to Redirect HTTP to HTTPS

​

/mintlify-assets/_next/static/*

• Set “Cache policy” to CachingOptimized
• Set “Origin request policy” to AllViewerExceptHostHeader
• Set “Viewer protocol policy” to Redirect HTTP to HTTPS

​

Default (*)

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

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

2. Select Save changes.

​

Check behaviors are set up correctly

If you follow the above steps, your behaviors should look like this:

​

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 your Mintlify documentation instance.

​

Connect with Route53

Now, we’re going to bring the functionality of the CloudFront distribution into your primary domain.

1. Navigate to Route53 inside the AWS console.
2. Navigate to the “Hosted zone” for your primary domain.
3. Select Create record.

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

5. Select Create records.

Your documentation is now live at /docs for your primary domain.