Deploy at a subpath with AWS Route 53 and CloudFront

Deploy your Mintlify documentation at a subpath on AWS by combining Route 53 DNS routing, a CloudFront distribution, and cache behaviors.

To host your documentation at a subpath such as yoursite.com/docs using AWS Route 53 and CloudFront, configure your DNS provider to point to your CloudFront distribution.

Before configuring AWS, set your base path in your dashboard:

1. Navigate to the Custom domain setup page in your dashboard.
2. Enable the Host at toggle.
3. Enter your domain.
4. Enter your base path. For example, /docs or /help.
5. Click Add domain.

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
• /_mintlify/* - Required for API playground requests

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

• /mintlify-assets/* - Required for CSS, JavaScript, and favicons
• Default (*) - Your website's landing page

All Behaviors must have an origin request policy of AllViewerExceptHostHeader.

The behaviors for your subpath must allow all HTTP methods. CloudFront only allows GET and HEAD requests by default. This blocks the POST requests that Mintlify uses for analytics and other interactive features.

1. Navigate to CloudFront inside the AWS console.
2. Click Create distribution.
3. For the Origin domain, input [SUBDOMAIN].mintlify.site 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. Click Create distribution.

1. After creating the distribution, navigate to the "Origins" tab.
2. Find your staging URL that mirrors the main domain. This varies depending on your landing page host. 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."

You should now have two Origins: one with [SUBDOMAIN].mintlify.site and another with your staging URL.

Behaviors in CloudFront enable control over the subpath logic. At a high level, you create the following logic:

• If a user lands on your custom subpath, go to [SUBDOMAIN].mintlify.site.
• If a user lands on any other page, go to the current landing page.

1. Navigate to the "Behaviors" tab of your CloudFront distribution.
2. Click the Create behavior button and create the following behaviors.

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.

Create a behavior with a Path pattern of your chosen subpath, for example /docs. Set Origin and origin groups to the .mintlify.site URL (for example, acme.mintlify.site).

• Set "Cache policy" to CachingDisabled.
• Set "Origin request policy" to AllViewerExceptHostHeader.
• Set "Viewer protocol policy" to Redirect HTTP to HTTPS.
• Set "Allowed HTTP methods" to GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE.

Create a behavior with a Path pattern of your chosen subpath followed by /*, for example /docs/*, and Origin and origin groups pointing to the same .mintlify.site URL.

These settings should exactly match your base subpath behavior, with the exception of the Path pattern.

• Set "Cache policy" to CachingDisabled.
• Set "Origin request policy" to AllViewerExceptHostHeader.
• Set "Viewer protocol policy" to Redirect HTTP to HTTPS.
• Set "Allowed HTTP methods" to GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE.

Create a behavior with a Path pattern of /mintlify-assets/* and set Origin and origin groups to the .mintlify.site URL. This path serves the CSS, JavaScript, and favicons for your documentation from the root of your domain.

• Set "Cache policy" to CachingOptimized.
• Set "Origin request policy" to AllViewerExceptHostHeader.
• Set "Viewer protocol policy" to Redirect HTTP to HTTPS.

Create a behavior with a Path pattern of /_mintlify/* and set Origin and origin groups to the .mintlify.site URL. This path handles API playground requests from the root of your domain.

• Set "Cache policy" to CachingDisabled.
• Set "Origin request policy" to AllViewerExceptHostHeader.
• Set "Viewer protocol policy" to Redirect HTTP to HTTPS.
• Set "Allowed HTTP methods" to GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE.

Edit the Default (*) behavior.

1. Change the default behavior's Origin and origin groups to the staging URL (for example, mintlify-landing-page.vercel.app).
2. Click Save changes.

If you follow the preceding steps, your distribution has six behaviors:

• /docs/*
• /docs
• /mintlify-assets/*
• /_mintlify/*
• /.well-known/*
• Default (*)

Confirm that each behavior points to the correct origin: the .mintlify.site URL for the docs, asset, API, and /.well-known/* paths, and your staging URL for Default (*).

To test your distribution, go to the "General" tab and visit the Distribution domain name URL.

All pages should route to your main landing page. When you append your chosen subpath, for example /docs, the URL should serve your Mintlify documentation.

Next, connect the CloudFront distribution to your primary domain.

First, add your domain to the CloudFront distribution. Without an alternate domain name, CloudFront rejects requests that arrive through your domain.

1. Open your distribution's "General" tab, then click Edit in the "Settings" section.
2. Add your domain (for example, yoursite.com) as an Alternate domain name (CNAME).
3. For "Custom SSL certificate," attach an AWS Certificate Manager (ACM) certificate that covers your domain.

1. Navigate to Route53 inside the AWS console.
2. Navigate to the "Hosted zone" for your primary domain.
3. Click Create record.
4. Toggle Alias and then Route traffic to the Alias to CloudFront distribution option.
5. Click Create records.

Your documentation is now live at your chosen subpath for your primary domain.

• Host docs at a subpath
• Deploy at a subpath with Vercel
• Deploy at a subpath with Cloudflare Workers