diff --git a/advanced/subpath/cloudflare.mdx b/advanced/subpath/cloudflare.mdx index 454383689..549605e29 100644 --- a/advanced/subpath/cloudflare.mdx +++ b/advanced/subpath/cloudflare.mdx @@ -19,6 +19,25 @@ Create a Cloudflare Worker by following the [Cloudflare Workers getting started If your DNS provider is Cloudflare, do not use proxying for the CNAME record. +### 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 @@ addEventListener("fetch", (event) => { 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 @@ async function handleRequest(request) { 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); } } @@ -110,6 +137,12 @@ If you use Webflow to host your main site and want to serve Mintlify docs at `/d 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 @@ If you use Webflow to host your main site and want to serve Mintlify docs at `/d 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 diff --git a/advanced/subpath/route53-cloudfront.mdx b/advanced/subpath/route53-cloudfront.mdx index 9207be3fd..416156b67 100644 --- a/advanced/subpath/route53-cloudfront.mdx +++ b/advanced/subpath/route53-cloudfront.mdx @@ -6,6 +6,31 @@ 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` @@ -70,11 +95,17 @@ Behaviors in Cloudfront enables control over the subpath logic. At a high level, - **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`) ![Cloudfront Behavior 1](/images/cloudfront/behavior-1.png) @@ -82,7 +113,7 @@ 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. ![Cloudfront Behavior 2](/images/cloudfront/behavior-2.png) diff --git a/advanced/subpath/vercel.mdx b/advanced/subpath/vercel.mdx index 859395776..4c8362ac8 100644 --- a/advanced/subpath/vercel.mdx +++ b/advanced/subpath/vercel.mdx @@ -3,10 +3,17 @@ 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 @@ following configuration to your `vercel.json` file. } ``` - - 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) - +- **`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.