Vercel proxy set up docs

advanced/subpath/cloudflare.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Cloudflare"
 description: "Host documentation at a /docs subpath using Cloudflare Workers"
 ---
 
 import Propagating from "/snippets/custom-subpath-propagating.mdx";
@@ -16,9 +16,28 @@
 Create a Cloudflare Worker by following the [Cloudflare Workers getting started guide](https://developers.cloudflare.com/workers/get-started/dashboard/), if you have not already.
 
 <Warning>
   If your DNS provider is Cloudflare, do not use proxying for the CNAME record.
 </Warning>
 
+### Proxies with Vercel deployments
+
+If you use Cloudflare as a proxy with Vercel deployments, you must ensure proper configuration to avoid conflicts with Vercel's domain verification and SSL certificate provisioning.
+
+Improper proxy configuration can prevent Vercel from provisioning Let's Encrypt SSL certificates and cause domain verification failures.
+
+#### Required path allowlist
+
+Your Cloudflare Worker must allow traffic to these specific paths without blocking or redirecting:
+
+- `/.well-known/acme-challenge/*` - Required for Let's Encrypt certificate verification
+- `/.well-known/vercel/*` - Required for Vercel domain verification
+
+While Cloudflare automatically handles many verification rules, creating additional custom rules may inadvertently block this critical traffic.
+
+#### Header forwarding requirements
+
+Ensure that the `HOST` header is correctly forwarded in your Worker configuration. Failure to properly forward headers will cause verification requests to fail.
+
 ### Configure routing
 
 In your Cloudflare dashboard, select **Edit Code** and add the following script into your Worker's code. See the [Cloudflare documentation](https://developers.cloudflare.com/workers-ai/get-started/dashboard/#development) for more information on editing a Worker.
@@ -35,6 +54,12 @@
 async function handleRequest(request) {
   try {
     const urlObject = new URL(request.url);
+
+    // If the request is to a Vercel verification path, allow it to pass through
+    if (urlObject.pathname.startsWith('/.well-known/')) {
+      return await fetch(request);
+    }
+
     // If the request is to the docs subdirectory
     if (/^\/docs/.test(urlObject.pathname)) {
       // Then Proxy to Mintlify
@@ -49,11 +74,13 @@
       proxyRequest.headers.set("Host", DOCS_URL);
       proxyRequest.headers.set("X-Forwarded-Host", CUSTOM_URL);
       proxyRequest.headers.set("X-Forwarded-Proto", "https");
+      // If deploying to Vercel, preserve client IP
+      proxyRequest.headers.set("CF-Connecting-IP", request.headers.get("CF-Connecting-IP"));
 
       return await fetch(proxyRequest);
     }
   } catch (error) {
-    // if no action found, play the regular request
+    // If no action found, play the regular request
     return await fetch(request);
   }
 }
@@ -77,7 +104,7 @@
 3. Add your domain. 
 
 <Tip>
   We recommend you add your domain both with and without `www.` prepended.
 </Tip>
 
 See [Add a custom domain](https://developers.cloudflare.com/workers/configuration/routing/custom-domains/#add-a-custom-domain) in the Cloudflare documentation for more information. 
@@ -89,14 +116,14 @@
 1. Delete the existing DNS record for your domain. See [Delete DNS records](https://developers.cloudflare.com/dns/manage-dns-records/how-to/create-dns-records/#delete-dns-records) in the Cloudflare documentation for more information.
 2. Return to your Worker and add your custom domain.
 
 ## Webflow custom routing
 If you use Webflow to host your main site and want to serve Mintlify docs at `/docs` on the same domain, you'll need to configure custom routing through Cloudflare Workers to proxy all non-docs traffic to your main site.
 
 <Warning>
   Make sure your main site is set up on a landing page before deploying this Worker, or visitors to your main site will see errors.
 </Warning>
 
 1. In Webflow, set up a landing page for your main site like `landing.yoursite.com`. This will be the page that visitors see when they visit your site.
 2. Deploy your main site to the landing page. This ensures that your main site remains accessible while you configure the Worker.
 3. To avoid conflicts, update any absolute URLs in your main site to be relative.
 4. In Cloudflare, select **Edit Code** and add the following script into your Worker's code.
@@ -110,6 +137,12 @@
   async function handleRequest(request) {
   try {
     const urlObject = new URL(request.url);
+
+    // If the request is to a Vercel verification path, allow it to pass through
+    if (urlObject.pathname.startsWith('/.well-known/')) {
+      return await fetch(request);
+    }
+
     // If the request is to the docs subdirectory
     if (/^\/docs/.test(urlObject.pathname)) {
       // Proxy to Mintlify
@@ -121,6 +154,8 @@
       proxyRequest.headers.set("Host", DOCS_URL);
       proxyRequest.headers.set("X-Forwarded-Host", CUSTOM_URL);
       proxyRequest.headers.set("X-Forwarded-Proto", "https");
+      // If deploying to Vercel, preserve client IP
+      proxyRequest.headers.set("CF-Connecting-IP", request.headers.get("CF-Connecting-IP"));
       return await fetch(proxyRequest);
     }
     // Route everything else to main site

advanced/subpath/route53-cloudfront.mdx

@@ -1,12 +1,37 @@
 ---
 title: "AWS Route 53 and Cloudfront"
 sidebarTitle: "AWS"
 description: "Host documentation at a /docs subdirectory using AWS services"
 ---
 
 import Propagating from "/snippets/custom-subpath-propagating.mdx";
 
+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](https://aws.amazon.com/cloudfront) inside the AWS console and click on `Create distribution`
 
@@ -42,10 +67,10 @@
 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.
 
 <Info>
 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.
 
 </Info>
 <Note>
@@ -61,28 +86,34 @@
   ![Cloudfront Default Origins](/images/cloudfront/default-origin.png)
 </Frame>
 
 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
 
-We're going to create three behaviors by clicking on the `Create behavior` button.
+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/*`
 
-The first behavior should have a **Path pattern** of `/docs/*` with **Origin and origin groups** pointing to the `.mintlify.dev` URL (in our case `acme.mintlify.dev`)
+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`)
 
 <Frame>![Cloudfront Behavior 1](/images/cloudfront/behavior-1.png)</Frame>
 
 For **Cache policy**, select `CachingOptimized` and create behavior.
 
 ### `/docs`
 
-The second behavior should be the same as the first one but with a **Path pattern** of `/docs` and **Origin and origin groups** pointing to the same `.mintlify.dev` URL.
+Create a behavior with a **Path pattern** of `/docs` and **Origin and origin groups** pointing to the same `.mintlify.dev` URL.
 
 <Frame>![Cloudfront Behavior 2](/images/cloudfront/behavior-2.png)</Frame>
 
@@ -115,7 +146,7 @@
 
 ## Connecting it 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

advanced/subpath/vercel.mdx

@@ -1,12 +1,19 @@
 ---
 title: "Vercel"
 description: "Host documentation at a /docs subpath using Vercel"
 ---
 
-## vercel.json Configuration
+## vercel.json file
 
-To host your documentation at a custom subpath using Vercel, you need to add the
-following configuration to your `vercel.json` file.
+The `vercel.json` file is Vercel's configuration file that allows you to customize how your project is built and deployed. It sits in your project's root directory and controls various aspects of your deployment, including routing, redirects, headers, and build settings.
+
+We use the `rewrites` configuration to proxy requests from your main domain to your documentation.
+
+Rewrites allow you to map incoming requests to different destinations without changing the URL in the browser. When someone visits `yoursite.com/docs`, Vercel will internally fetch content from `your-subdomain.mintlify.dev/docs` but the user will still see `yoursite.com/docs` in their browser. This is different from redirects, which would send users to a different URL entirely.
+
+## Configuration
+
+To host your documentation at a custom `/docs` subpath using Vercel, add the following configuration to your `vercel.json` file:
 
 ```json
 {
@@ -23,8 +30,38 @@
 }
 ```
 
-<Note>
-  For more information, you can also refer to Vercel's offical guide on
-  rewrites: [Project Configuration:
-  Rewrites](https://vercel.com/docs/projects/project-configuration#rewrites)
-</Note>
+- **`source`**: The path pattern on your domain that triggers the rewrite.
+- **`destination`**: Where the request should be proxied to.
+- **`:match*`**: A wildcard that captures any path segments after `/docs/`.
+
+
+For more information, see [Configuring projects with vercel.json: Rewrites](https://vercel.com/docs/projects/project-configuration#rewrites) in the Vercel documentation.
+
+## Using external proxies with Vercel
+
+If you're using an external proxy (like Cloudflare or AWS CloudFront) in front of your Vercel deployment, you must configure it properly to avoid conflicts with Vercel's domain verification and SSL certificate provisioning.
+
+Improper proxy configuration can prevent Vercel from provisioning Let's Encrypt SSL certificates and cause domain verification failures.
+
+See the [supported providers](https://vercel.com/guides/how-to-setup-verified-proxy#supported-providers-verified-proxy-lite) in the Vercel documentation.
+
+### Required path allowlist
+
+Your external proxy must allow traffic to these specific paths without blocking, redirecting, or heavily caching:
+
+- `/.well-known/acme-challenge/*` - Required for Let's Encrypt certificate verification
+- `/.well-known/vercel/*` - Required for Vercel domain verification
+
+These paths should pass through directly to your Vercel deployment without modification.
+
+### Header forwarding requirements
+
+Ensure that your proxy correctly forwards the `HOST` header. Without proper header forwarding, verification requests will fail.
+
+### Testing your proxy setup
+
+To verify your proxy is correctly configured:
+
+1. Test that `https://[yourdomain].com/.well-known/vercel/` returns a response.
+2. Ensure SSL certificates are provisioning correctly in your Vercel dashboard.
+3. Check that domain verification completes successfully.