mintlify__docs/deploy/route53-cloudfront.mdx

---
title: "AWS Route 53 and CloudFront"
sidebarTitle: "AWS"
description: "Deploy documentation at a subpath on AWS with Route 53 DNS and CloudFront CDN."
keywords: ["AWS deployment", "Route 53 DNS", "CloudFront CDN", "cache policies"]
---

import Propagating from "/snippets/custom-subpath-propagating.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.

## 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 website's landing page

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

![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. Select **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.dev` where `[SUBDOMAIN]` is your project's unique subdomain.

  <Frame>
    ![CloudFront "Create distribution" page showing "acme.mintlify.dev" 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>

5. The remaining settings should be default.
6. Select **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 is highly variant depending on how your landing page is hosted. For example, the Mintlify staging URL is [mintlify-landing-page.vercel.app](https://mintlify-landing-page.vercel.app).

<Info>
  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.
</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>

By this point, you should have two Origins: one with `[SUBDOMAIN].mintlify.app` 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, we're looking to create the following logic:

- **If a user lands on your custom subpath**, 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.

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

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.

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

<Frame>
  ![CloudFront "Create behavior" page with a "Path pattern" of "/docs/*" and "Origin and origin groups" pointing to the `acme.mintlify.dev` 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.dev` URL.

These settings should exactly match your base subpath behavior. 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.

<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 (in our case `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. Select **Save changes**.

### Check behaviors are set up correctly

If you follow the above 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

You can now test if your distribution is set up properly by going to the "General" tab and visiting 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 be directing to your main landing page, but if you append your chosen subpath, for example `/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.

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