mintlify__docs/deploy/route53-cloudfront.mdx

---
title: "AWS Route 53 and CloudFront"
sidebarTitle: "AWS"
description: "Deploy your Mintlify documentation at a subpath on AWS using Route 53 for DNS routing and CloudFront as a CDN with Lambda@Edge functions."
keywords: ["AWS deployment", "Route 53 DNS", "CloudFront CDN", "cache policies"]
---

import Propagating from "/snippets/custom-subpath-propagating.mdx";
import SubpathSetupSteps from "/snippets/subpath-setup-steps.mdx";

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

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

<SubpathSetupSteps />

## Overview

<Note>
  The following examples use the `/docs` base path. If you use a different base path, replace `/docs` with your base path.
</Note>

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 these paths with a Cache Policy of **CachingEnabled**:

- `/mintlify-assets/_next/static/*`
- `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, which blocks the `POST` requests that Mintlify uses for analytics and other interactive features.

![CloudFront "Behaviors" page with 4 behaviors: `/docs/*`, `/docs`, `Default`, and `/.well-known/*`.](/images/cloudfront/all-behaviors.png)

## Create CloudFront distribution

1. Navigate to [CloudFront](https://aws.amazon.com/cloudfront) inside the AWS console.
2. Click **Create distribution**.

  <Frame>
    ![CloudFront Distributions page with the "Create distribution" button emphasized.](/images/cloudfront/create-distribution.png)
  </Frame>

3. For the Origin domain, input `[SUBDOMAIN].mintlify.site` where `[SUBDOMAIN]` is your project's unique subdomain.

  <Frame>
    ![CloudFront "Create distribution" page showing "acme.mintlify.site" as the origin domain.](/images/cloudfront/origin-name.png)
  </Frame>

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

  <Frame>
    ![Web Application Firewall (WAF) options with "Enable security protections" selected.](/images/cloudfront/enable-security-protections.png)
  </Frame>

  <Note>
    WAF rules can block the `POST` requests that Mintlify uses for analytics and other interactive features. If analytics stop appearing in your dashboard after enabling WAF, check your WAF logs for blocked requests to paths under `/docs/_mintlify/`.
  </Note>

5. The remaining settings should be default.
6. Click **Create distribution**.

## Add default origin

1. After creating the distribution, navigate to the "Origins" tab.

  <Frame>
    ![A CloudFront distribution with the "Origins" tab highlighted.](/images/cloudfront/origins.png)
  </Frame>

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](https://mintlify-landing-page.vercel.app).

<Info>
  {/* vale Vale.Terms = NO */}
  If Webflow hosts your landing page, use Webflow's staging URL. It would look like `.webflow.io`.
  {/* vale Vale.Terms = YES */}

  If you use Vercel, use the `.vercel.app` domain available for every project.
</Info>

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

  <Frame>
    ![CloudFront "Create origin" page with a "Origin domain" input field highlighted.](/images/cloudfront/default-origin.png)
  </Frame>

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

<Frame>
  ![CloudFront "Origins" page with two origins: One for `mintlify` and another for `mintlify-landing-page`.](/images/cloudfront/final-origins.png)
</Frame>

## Set behaviors

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.

<Frame>
	![CloudFront "Behaviors" tab highlighted.](/images/cloudfront/behaviors.png)
</Frame>

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

<Frame>
  ![CloudFront "Create behavior" page with a "Path pattern" of "/.well-known/*" and "Origin and origin groups" pointing to the staging URL.](/images/cloudfront/well-known-policy.png)
</Frame>

<Info>
If `.well-known/*` is too generic, you can narrow it 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
</Info>

### Your subpath

Create a behavior with a **Path pattern** of your chosen subpath, for example `/docs`, with **Origin and origin groups** pointing 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**.

<Warning>
  CloudFront only allows `GET` and `HEAD` requests by default. If you don't allow all HTTP methods, CloudFront rejects the `POST` requests that Mintlify uses for analytics, and your dashboard won't show any page views even though your docs load normally.
</Warning>

<Frame>
  ![CloudFront "Create behavior" page with a "Path pattern" of "/docs/*" and "Origin and origin groups" pointing to the `acme.mintlify.site` URL.](/images/cloudfront/behavior-1.png)
</Frame>

### Your subpath with wildcard

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

### `/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 (*)`

Edit the `Default (*)` behavior.

<Frame>
  ![A CloudFront distribution with the "Default (*)" behavior selected and the Edit button emphasized.](/images/cloudfront/default-behavior-1.png)
</Frame>

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

<Frame>
  ![CloudFront "Edit behavior" page with the "Origin and origin groups" input field highlighted.](/images/cloudfront/default-behavior-2.png)
</Frame>

2. Click **Save changes**.

### Check that you set up behaviors correctly

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

<Frame>
  ![CloudFront "Behaviors" page with 4 behaviors: `/docs/*`, `/docs`, `Default`, and `/.well-known/*`.](/images/cloudfront/all-behaviors.png)
</Frame>

## Preview distribution

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

<Frame>
  ![CloudFront "General" tab with the "Distribution domain name" URL highlighted.](/images/cloudfront/preview-distribution.png)
</Frame>

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.

## Connect with Route 53

Next, connect the CloudFront distribution to your primary domain.

<Note>
  For this section, you can also refer to AWS's official guide on [Configuring
  Amazon Route 53 to route traffic to a CloudFront
  distribution](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-cloudfront-distribution.html#routing-to-cloudfront-distribution-config)
</Note>

1. Navigate to [Route53](https://aws.amazon.com/route53) inside the AWS console.
2. Navigate to the "Hosted zone" for your primary domain.
3. Click **Create record**.

<Frame>
  ![Route 53 "Records" page with the "Create record" button emphasized.](/images/cloudfront/route53-create-record.png)
</Frame>

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

<Frame>
  ![Route 53 "Create record" page with the "Alias" toggle and the "Route traffic to" menu highlighted.](/images/cloudfront/create-record-alias.png)
</Frame>

5. Click **Create records**.

<Note>
  You may need to remove the existing A record if one currently exists.
</Note>

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

<Propagating />