From 5e8a61dcb9200762804ab59c318fbcb66dcf3f44 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Thu, 18 Sep 2025 02:43:19 +0000 Subject: [PATCH 01/22] Update advanced/reverse-proxy.mdx --- advanced/reverse-proxy.mdx | 273 +++++++++++++++++++++++++++++++++++++ 1 file changed, 273 insertions(+) create mode 100644 advanced/reverse-proxy.mdx diff --git a/advanced/reverse-proxy.mdx b/advanced/reverse-proxy.mdx new file mode 100644 index 000000000..09378ea6f --- /dev/null +++ b/advanced/reverse-proxy.mdx @@ -0,0 +1,273 @@ +--- +title: "Custom reverse proxy" +description: "Configure a custom reverse proxy to serve Mintlify documentation" +--- + +import Propagating from "/snippets/custom-subpath-propagating.mdx"; + + + **Enterprise support required**: Custom reverse proxy configurations require an enterprise contract for support. This guide is provided for self-service implementation only. + + +To serve your Mintlify documentation through a custom reverse proxy, you need to configure specific routing rules, caching policies, and header forwarding to ensure proper functionality. + + + This guide provides general configuration principles. Implementation details vary significantly between proxy solutions (nginx, Apache, HAProxy, AWS ALB, etc.). + + +## High-level overview + +Configure your reverse proxy with these routing and caching rules: + +### Cache Policy: CachingDisabled + +Route traffic to these paths **without caching**: + +- `/.well-known/acme-challenge/*` - Required for Let's Encrypt certificate verification +- `/.well-known/vercel/*` - Required for domain verification +- `/*` - Required for base path routing +- `/` - Required for base path routing + +### Cache Policy: CachingEnabled + +Route traffic to these paths **with caching**: + +- `/mintlify-assets/_next/static/*` - Static assets (CSS, JS, images) +- `Default (*)` - Your website's landing page + +### Origin Request Policy + +**DO NOT FORWARD THE HOST HEADER** - All behaviors must use an origin request policy equivalent to `AllViewerExceptHostHeader`. + +## Required header configuration + +Your reverse proxy must forward these headers to ensure proper functionality: + +### Required headers + +```nginx +# Example nginx configuration +location / { + proxy_pass https://.mintlify.app/; + + # CRITICAL: Set the correct origin header + proxy_set_header Origin .mintlify.app; + + # Forward client information + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + + # DO NOT forward the Host header - this will break functionality + # proxy_set_header Host $host; # ← DO NOT INCLUDE THIS LINE +} +``` + +### Critical header requirements + + + **DO NOT FORWARD THE HOST HEADER** - Forwarding the `Host` header will cause domain verification failures and break core functionality. + + +1. **Origin header**: Must be set to `.mintlify.app` +2. **X-Forwarded-For**: Preserve client IP information +3. **X-Forwarded-Proto**: Preserve original protocol (HTTP/HTTPS) +4. **X-Real-IP**: Forward the real client IP address + +## Domain verification paths + +Your reverse proxy must allow these verification paths to pass through without modification: + +### Let's Encrypt verification +``` +/.well-known/acme-challenge/* +``` + +### Vercel domain verification +``` +/.well-known/vercel/* +``` + +These paths are essential for SSL certificate provisioning and domain ownership verification. Blocking or modifying requests to these paths will prevent proper setup. + +## Example configurations + +### nginx + +```nginx +server { + listen 80; + server_name yourdomain.com; + + # Let's Encrypt and Vercel verification paths + location ~ ^/\.well-known/(acme-challenge|vercel)/ { + proxy_pass https://your-subdomain.mintlify.app; + proxy_set_header Origin your-subdomain.mintlify.app; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + + # Disable caching for verification paths + proxy_cache off; + add_header Cache-Control "no-cache, no-store, must-revalidate"; + } + + # Static assets with caching + location ~ ^/mintlify-assets/_next/static/ { + proxy_pass https://your-subdomain.mintlify.app; + proxy_set_header Origin your-subdomain.mintlify.app; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + + # Enable caching for static assets + proxy_cache_valid 200 1d; + add_header Cache-Control "public, max-age=86400"; + } + + # All other documentation paths + location / { + proxy_pass https://your-subdomain.mintlify.app/; + proxy_set_header Origin your-subdomain.mintlify.app; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + + # Disable caching for dynamic content + proxy_cache off; + add_header Cache-Control "no-cache, no-store, must-revalidate"; + } +} +``` + +### Apache + +```apache + + ServerName yourdomain.com + + # Enable proxy module + ProxyPreserveHost Off + ProxyRequests Off + + # Let's Encrypt and Vercel verification paths + ProxyPassMatch ^/\.well-known/(acme-challenge|vercel)/(.*) https://your-subdomain.mintlify.app/.well-known/$1/$2 + ProxyPassReverseMatch ^/\.well-known/(acme-challenge|vercel)/(.*) https://your-subdomain.mintlify.app/.well-known/$1/$2 + + # Static assets + ProxyPassMatch ^/mintlify-assets/_next/static/(.*) https://your-subdomain.mintlify.app/mintlify-assets/_next/static/$1 + ProxyPassReverseMatch ^/mintlify-assets/_next/static/(.*) https://your-subdomain.mintlify.app/mintlify-assets/_next/static/$1 + + # All other paths + ProxyPass / https://your-subdomain.mintlify.app/ + ProxyPassReverse / https://your-subdomain.mintlify.app/ + + # Set required headers + ProxyPassReverse / https://your-subdomain.mintlify.app/ + RequestHeader set Origin "your-subdomain.mintlify.app" + RequestHeader set X-Forwarded-Proto "http" + +``` + +### HAProxy + +```haproxy +frontend docs_frontend + bind *:80 + + # Route verification paths + acl is_verification path_beg /.well-known/acme-challenge /.well-known/vercel + use_backend mintlify_backend if is_verification + + # Route static assets + acl is_static path_beg /mintlify-assets/_next/static + use_backend mintlify_backend if is_static + + # Default backend for all other requests + default_backend mintlify_backend + +backend mintlify_backend + server mintlify your-subdomain.mintlify.app:443 ssl verify none + + # Set required headers + http-request set-header Origin your-subdomain.mintlify.app + http-request set-header X-Forwarded-Proto http + http-request del-header Host +``` + +## Testing your configuration + +After configuring your reverse proxy, test these critical paths: + +### 1. Basic functionality +```bash +curl -H "Host: yourdomain.com" http://your-proxy-server/ +``` + +### 2. Verification paths +```bash +curl -H "Host: yourdomain.com" http://your-proxy-server/.well-known/vercel/test +curl -H "Host: yourdomain.com" http://your-proxy-server/.well-known/acme-challenge/test +``` + +### 3. Static assets +```bash +curl -H "Host: yourdomain.com" http://your-proxy-server/mintlify-assets/_next/static/test.css +``` + +### 4. Header verification +```bash +curl -v -H "Host: yourdomain.com" http://your-proxy-server/ 2>&1 | grep -E "(Origin|X-Forwarded|Host):" +``` + +## Common issues and troubleshooting + +### Domain verification failures + +**Symptoms**: SSL certificate provisioning fails, domain verification errors + +**Cause**: Verification paths (`/.well-known/*`) are blocked or modified + +**Solution**: Ensure verification paths pass through without caching or modification + +### Broken functionality + +**Symptoms**: Documentation loads but features don't work, API calls fail + +**Cause**: Host header is being forwarded or Origin header is missing + +**Solution**: +- Remove `Host` header forwarding +- Set `Origin` header to `.mintlify.app` + +### Performance issues + +**Symptoms**: Slow loading, repeated requests for static assets + +**Cause**: Incorrect caching configuration + +**Solution**: Enable caching only for `/mintlify-assets/_next/static/*` paths + +### SSL/TLS errors + +**Symptoms**: Certificate errors, mixed content warnings + +**Cause**: Incorrect protocol forwarding + +**Solution**: Ensure `X-Forwarded-Proto` header reflects the original request protocol + +## Support limitations + + + Custom reverse proxy configurations are **not officially supported** without an enterprise contract. Common issues include: + + - Domain verification failures + - SSL certificate provisioning problems + - Broken authentication flows + - Performance degradation + - Analytics tracking issues + + +For production deployments requiring reverse proxy configurations, contact your account manager to discuss enterprise support options. + + \ No newline at end of file From 3d41867dca537a72d45c3bee1f06af4d8fd65eea Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Thu, 18 Sep 2025 02:45:38 +0000 Subject: [PATCH 02/22] Update docs.json --- docs.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs.json b/docs.json index e364b4726..9f3d7ff73 100644 --- a/docs.json +++ b/docs.json @@ -160,6 +160,7 @@ "advanced/subpath/cloudflare", "advanced/subpath/route53-cloudfront", "advanced/subpath/vercel", + "advanced/reverse-proxy", "guides/csp-configuration" ] }, @@ -551,4 +552,4 @@ "publicApiKey": "pk_76a6caa274e800f3ceff0b2bc6b9b9d82ab8" } } -} +} \ No newline at end of file From eac73e8dd4619d569b053b43accceddee009173f Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Thu, 18 Sep 2025 02:48:05 +0000 Subject: [PATCH 03/22] Documentation edits made through Mintlify web editor --- advanced/reverse-proxy.mdx | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/advanced/reverse-proxy.mdx b/advanced/reverse-proxy.mdx index 09378ea6f..73d759da4 100644 --- a/advanced/reverse-proxy.mdx +++ b/advanced/reverse-proxy.mdx @@ -24,7 +24,7 @@ Configure your reverse proxy with these routing and caching rules: Route traffic to these paths **without caching**: - `/.well-known/acme-challenge/*` - Required for Let's Encrypt certificate verification -- `/.well-known/vercel/*` - Required for domain verification +- `/.well-known/vercel/*` - Required for domain verification - `/*` - Required for base path routing - `/` - Required for base path routing @@ -35,10 +35,6 @@ Route traffic to these paths **with caching**: - `/mintlify-assets/_next/static/*` - Static assets (CSS, JS, images) - `Default (*)` - Your website's landing page -### Origin Request Policy - -**DO NOT FORWARD THE HOST HEADER** - All behaviors must use an origin request policy equivalent to `AllViewerExceptHostHeader`. - ## Required header configuration Your reverse proxy must forward these headers to ensure proper functionality: @@ -79,11 +75,13 @@ location / { Your reverse proxy must allow these verification paths to pass through without modification: ### Let's Encrypt verification + ``` /.well-known/acme-challenge/* ``` -### Vercel domain verification +### Vercel domain verification + ``` /.well-known/vercel/* ``` @@ -200,22 +198,26 @@ backend mintlify_backend After configuring your reverse proxy, test these critical paths: ### 1. Basic functionality + ```bash curl -H "Host: yourdomain.com" http://your-proxy-server/ ``` ### 2. Verification paths + ```bash curl -H "Host: yourdomain.com" http://your-proxy-server/.well-known/vercel/test curl -H "Host: yourdomain.com" http://your-proxy-server/.well-known/acme-challenge/test ``` ### 3. Static assets + ```bash curl -H "Host: yourdomain.com" http://your-proxy-server/mintlify-assets/_next/static/test.css ``` ### 4. Header verification + ```bash curl -v -H "Host: yourdomain.com" http://your-proxy-server/ 2>&1 | grep -E "(Origin|X-Forwarded|Host):" ``` @@ -236,7 +238,8 @@ curl -v -H "Host: yourdomain.com" http://your-proxy-server/ 2>&1 | grep -E "(Ori **Cause**: Host header is being forwarded or Origin header is missing -**Solution**: +**Solution**: + - Remove `Host` header forwarding - Set `Origin` header to `.mintlify.app` @@ -260,9 +263,9 @@ curl -v -H "Host: yourdomain.com" http://your-proxy-server/ 2>&1 | grep -E "(Ori Custom reverse proxy configurations are **not officially supported** without an enterprise contract. Common issues include: - + - Domain verification failures - - SSL certificate provisioning problems + - SSL certificate provisioning problems - Broken authentication flows - Performance degradation - Analytics tracking issues From 83b85401c35d0dfc00d43e46ce80523062324dbe Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Thu, 18 Sep 2025 02:54:28 +0000 Subject: [PATCH 04/22] Update advanced/reverse-proxy.mdx --- advanced/reverse-proxy.mdx | 76 +++++++++----------------------------- 1 file changed, 18 insertions(+), 58 deletions(-) diff --git a/advanced/reverse-proxy.mdx b/advanced/reverse-proxy.mdx index 73d759da4..1d9a15f08 100644 --- a/advanced/reverse-proxy.mdx +++ b/advanced/reverse-proxy.mdx @@ -88,9 +88,7 @@ Your reverse proxy must allow these verification paths to pass through without m These paths are essential for SSL certificate provisioning and domain ownership verification. Blocking or modifying requests to these paths will prevent proper setup. -## Example configurations - -### nginx +## nginx configuration ```nginx server { @@ -104,6 +102,7 @@ server { proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header User-Agent $http_user_agent; # Disable caching for verification paths proxy_cache off; @@ -117,12 +116,27 @@ server { proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header User-Agent $http_user_agent; # Enable caching for static assets proxy_cache_valid 200 1d; add_header Cache-Control "public, max-age=86400"; } + # MCP troubleshooting path - requires User-Agent header + location /mcp { + proxy_pass https://your-subdomain.mintlify.app/mcp; + proxy_set_header Origin your-subdomain.mintlify.app; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header User-Agent $http_user_agent; # REQUIRED for /mcp functionality + + # Disable caching for troubleshooting + proxy_cache off; + add_header Cache-Control "no-cache, no-store, must-revalidate"; + } + # All other documentation paths location / { proxy_pass https://your-subdomain.mintlify.app/; @@ -130,6 +144,7 @@ server { proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header User-Agent $http_user_agent; # Disable caching for dynamic content proxy_cache off; @@ -138,61 +153,6 @@ server { } ``` -### Apache - -```apache - - ServerName yourdomain.com - - # Enable proxy module - ProxyPreserveHost Off - ProxyRequests Off - - # Let's Encrypt and Vercel verification paths - ProxyPassMatch ^/\.well-known/(acme-challenge|vercel)/(.*) https://your-subdomain.mintlify.app/.well-known/$1/$2 - ProxyPassReverseMatch ^/\.well-known/(acme-challenge|vercel)/(.*) https://your-subdomain.mintlify.app/.well-known/$1/$2 - - # Static assets - ProxyPassMatch ^/mintlify-assets/_next/static/(.*) https://your-subdomain.mintlify.app/mintlify-assets/_next/static/$1 - ProxyPassReverseMatch ^/mintlify-assets/_next/static/(.*) https://your-subdomain.mintlify.app/mintlify-assets/_next/static/$1 - - # All other paths - ProxyPass / https://your-subdomain.mintlify.app/ - ProxyPassReverse / https://your-subdomain.mintlify.app/ - - # Set required headers - ProxyPassReverse / https://your-subdomain.mintlify.app/ - RequestHeader set Origin "your-subdomain.mintlify.app" - RequestHeader set X-Forwarded-Proto "http" - -``` - -### HAProxy - -```haproxy -frontend docs_frontend - bind *:80 - - # Route verification paths - acl is_verification path_beg /.well-known/acme-challenge /.well-known/vercel - use_backend mintlify_backend if is_verification - - # Route static assets - acl is_static path_beg /mintlify-assets/_next/static - use_backend mintlify_backend if is_static - - # Default backend for all other requests - default_backend mintlify_backend - -backend mintlify_backend - server mintlify your-subdomain.mintlify.app:443 ssl verify none - - # Set required headers - http-request set-header Origin your-subdomain.mintlify.app - http-request set-header X-Forwarded-Proto http - http-request del-header Host -``` - ## Testing your configuration After configuring your reverse proxy, test these critical paths: From 593550f69f255ca4d380f074bc827b68b785dd24 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Thu, 18 Sep 2025 02:54:43 +0000 Subject: [PATCH 05/22] Update advanced/reverse-proxy.mdx --- advanced/reverse-proxy.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/advanced/reverse-proxy.mdx b/advanced/reverse-proxy.mdx index 1d9a15f08..aca365796 100644 --- a/advanced/reverse-proxy.mdx +++ b/advanced/reverse-proxy.mdx @@ -53,6 +53,7 @@ location / { proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header User-Agent $http_user_agent; # DO NOT forward the Host header - this will break functionality # proxy_set_header Host $host; # ← DO NOT INCLUDE THIS LINE @@ -69,6 +70,7 @@ location / { 2. **X-Forwarded-For**: Preserve client IP information 3. **X-Forwarded-Proto**: Preserve original protocol (HTTP/HTTPS) 4. **X-Real-IP**: Forward the real client IP address +5. **User-Agent**: Forward the original User-Agent header (required for `/mcp` troubleshooting functionality) ## Domain verification paths From 6c40350048039b37e9b62384b24ea7a49bcd1a53 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Thu, 18 Sep 2025 02:54:48 +0000 Subject: [PATCH 06/22] Update advanced/reverse-proxy.mdx --- advanced/reverse-proxy.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/advanced/reverse-proxy.mdx b/advanced/reverse-proxy.mdx index aca365796..a9a4cd6bf 100644 --- a/advanced/reverse-proxy.mdx +++ b/advanced/reverse-proxy.mdx @@ -12,7 +12,7 @@ import Propagating from "/snippets/custom-subpath-propagating.mdx"; To serve your Mintlify documentation through a custom reverse proxy, you need to configure specific routing rules, caching policies, and header forwarding to ensure proper functionality. - This guide provides general configuration principles. Implementation details vary significantly between proxy solutions (nginx, Apache, HAProxy, AWS ALB, etc.). + This guide provides nginx configuration examples. For other proxy solutions, adapt the header forwarding and routing principles accordingly. ## High-level overview From 21471de8914c6b78adbf1ef37c160447dbaab36c Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Thu, 18 Sep 2025 03:01:19 +0000 Subject: [PATCH 07/22] Documentation edits made through Mintlify web editor --- advanced/reverse-proxy.mdx | 94 ++++++++++++++++++++++++++------------ 1 file changed, 64 insertions(+), 30 deletions(-) diff --git a/advanced/reverse-proxy.mdx b/advanced/reverse-proxy.mdx index a9a4cd6bf..d25c3fb78 100644 --- a/advanced/reverse-proxy.mdx +++ b/advanced/reverse-proxy.mdx @@ -12,23 +12,19 @@ import Propagating from "/snippets/custom-subpath-propagating.mdx"; To serve your Mintlify documentation through a custom reverse proxy, you need to configure specific routing rules, caching policies, and header forwarding to ensure proper functionality. - This guide provides nginx configuration examples. For other proxy solutions, adapt the header forwarding and routing principles accordingly. + This guide provides general configuration principles. Implementation details vary significantly between proxy solutions (nginx, Apache, HAProxy, AWS ALB, etc.). ## High-level overview Configure your reverse proxy with these routing and caching rules: -### Cache Policy: CachingDisabled - Route traffic to these paths **without caching**: -- `/.well-known/acme-challenge/*` - Required for Let's Encrypt certificate verification -- `/.well-known/vercel/*` - Required for domain verification -- `/*` - Required for base path routing -- `/` - Required for base path routing - -### Cache Policy: CachingEnabled +- `/.well-known/acme-challenge/*` -\> \.mintlify.app +- `/.well-known/vercel/*` -\> \.mintlify.app +- `/*` -\> \.minltify.app +- `/` -\> \.mintlify.app Route traffic to these paths **with caching**: @@ -53,7 +49,6 @@ location / { proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; - proxy_set_header User-Agent $http_user_agent; # DO NOT forward the Host header - this will break functionality # proxy_set_header Host $host; # ← DO NOT INCLUDE THIS LINE @@ -70,7 +65,6 @@ location / { 2. **X-Forwarded-For**: Preserve client IP information 3. **X-Forwarded-Proto**: Preserve original protocol (HTTP/HTTPS) 4. **X-Real-IP**: Forward the real client IP address -5. **User-Agent**: Forward the original User-Agent header (required for `/mcp` troubleshooting functionality) ## Domain verification paths @@ -90,7 +84,9 @@ Your reverse proxy must allow these verification paths to pass through without m These paths are essential for SSL certificate provisioning and domain ownership verification. Blocking or modifying requests to these paths will prevent proper setup. -## nginx configuration +## Example configurations + +### nginx ```nginx server { @@ -104,7 +100,6 @@ server { proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; - proxy_set_header User-Agent $http_user_agent; # Disable caching for verification paths proxy_cache off; @@ -118,27 +113,12 @@ server { proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; - proxy_set_header User-Agent $http_user_agent; # Enable caching for static assets proxy_cache_valid 200 1d; add_header Cache-Control "public, max-age=86400"; } - # MCP troubleshooting path - requires User-Agent header - location /mcp { - proxy_pass https://your-subdomain.mintlify.app/mcp; - proxy_set_header Origin your-subdomain.mintlify.app; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $scheme; - proxy_set_header User-Agent $http_user_agent; # REQUIRED for /mcp functionality - - # Disable caching for troubleshooting - proxy_cache off; - add_header Cache-Control "no-cache, no-store, must-revalidate"; - } - # All other documentation paths location / { proxy_pass https://your-subdomain.mintlify.app/; @@ -146,7 +126,6 @@ server { proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; - proxy_set_header User-Agent $http_user_agent; # Disable caching for dynamic content proxy_cache off; @@ -155,6 +134,61 @@ server { } ``` +### Apache + +```apache + + ServerName yourdomain.com + + # Enable proxy module + ProxyPreserveHost Off + ProxyRequests Off + + # Let's Encrypt and Vercel verification paths + ProxyPassMatch ^/\.well-known/(acme-challenge|vercel)/(.*) https://your-subdomain.mintlify.app/.well-known/$1/$2 + ProxyPassReverseMatch ^/\.well-known/(acme-challenge|vercel)/(.*) https://your-subdomain.mintlify.app/.well-known/$1/$2 + + # Static assets + ProxyPassMatch ^/mintlify-assets/_next/static/(.*) https://your-subdomain.mintlify.app/mintlify-assets/_next/static/$1 + ProxyPassReverseMatch ^/mintlify-assets/_next/static/(.*) https://your-subdomain.mintlify.app/mintlify-assets/_next/static/$1 + + # All other paths + ProxyPass / https://your-subdomain.mintlify.app/ + ProxyPassReverse / https://your-subdomain.mintlify.app/ + + # Set required headers + ProxyPassReverse / https://your-subdomain.mintlify.app/ + RequestHeader set Origin "your-subdomain.mintlify.app" + RequestHeader set X-Forwarded-Proto "http" + +``` + +### HAProxy + +```haproxy +frontend docs_frontend + bind *:80 + + # Route verification paths + acl is_verification path_beg /.well-known/acme-challenge /.well-known/vercel + use_backend mintlify_backend if is_verification + + # Route static assets + acl is_static path_beg /mintlify-assets/_next/static + use_backend mintlify_backend if is_static + + # Default backend for all other requests + default_backend mintlify_backend + +backend mintlify_backend + server mintlify your-subdomain.mintlify.app:443 ssl verify none + + # Set required headers + http-request set-header Origin your-subdomain.mintlify.app + http-request set-header X-Forwarded-Proto http + http-request del-header Host +``` + ## Testing your configuration After configuring your reverse proxy, test these critical paths: @@ -194,7 +228,7 @@ curl -v -H "Host: yourdomain.com" http://your-proxy-server/ 2>&1 | grep -E "(Ori **Solution**: Ensure verification paths pass through without caching or modification -### Broken functionality +### 404 Error Not Found **Symptoms**: Documentation loads but features don't work, API calls fail From dc8d37bbba66e2e0f211c5a8146cad01739834f8 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Thu, 18 Sep 2025 03:08:17 +0000 Subject: [PATCH 08/22] Documentation edits made through Mintlify web editor --- advanced/reverse-proxy.mdx | 167 ++++--------------------------------- 1 file changed, 18 insertions(+), 149 deletions(-) diff --git a/advanced/reverse-proxy.mdx b/advanced/reverse-proxy.mdx index d25c3fb78..dbcf98d16 100644 --- a/advanced/reverse-proxy.mdx +++ b/advanced/reverse-proxy.mdx @@ -5,35 +5,31 @@ description: "Configure a custom reverse proxy to serve Mintlify documentation" import Propagating from "/snippets/custom-subpath-propagating.mdx"; - - **Enterprise support required**: Custom reverse proxy configurations require an enterprise contract for support. This guide is provided for self-service implementation only. - - -To serve your Mintlify documentation through a custom reverse proxy, you need to configure specific routing rules, caching policies, and header forwarding to ensure proper functionality. - - - This guide provides general configuration principles. Implementation details vary significantly between proxy solutions (nginx, Apache, HAProxy, AWS ALB, etc.). - +Custom reverse proxy configurations are **not officially supported** without an enterprise contract. To serve your Mintlify documentation through a custom reverse proxy, you need to configure specific routing rules, caching policies, and header forwarding to ensure proper functionality. ## High-level overview Configure your reverse proxy with these routing and caching rules: -Route traffic to these paths **without caching**: +### Route traffic to these paths **without caching**: -- `/.well-known/acme-challenge/*` -\> \.mintlify.app -- `/.well-known/vercel/*` -\> \.mintlify.app -- `/*` -\> \.minltify.app -- `/` -\> \.mintlify.app +- `/.well-known/acme-challenge/*` -\> `.mintlify.app` +- `/.well-known/vercel/*` -\> `.mintlify.app` +- `/*` -\> `.minltify.app` +- `/` -\> `.mintlify.app` -Route traffic to these paths **with caching**: +### Route traffic to these paths **with caching**: -- `/mintlify-assets/_next/static/*` - Static assets (CSS, JS, images) -- `Default (*)` - Your website's landing page +- `/mintlify-assets/_next/static/*` -\> `.mintlify.app/mintlify-assets/_next/static/` ## Required header configuration -Your reverse proxy must forward these headers to ensure proper functionality: +Your reverse proxy must forward these headers: + +1. **Origin header**: Must be set to `.mintlify.app` +2. **X-Forwarded-For**: Preserve client IP information +3. **X-Forwarded-Proto**: Preserve original protocol (HTTP/HTTPS) +4. **X-Real-IP**: Forward the real client IP address ### Required headers @@ -55,35 +51,10 @@ location / { } ``` -### Critical header requirements - - **DO NOT FORWARD THE HOST HEADER** - Forwarding the `Host` header will cause domain verification failures and break core functionality. + Ensurre that the `Host` header is not forwarded -1. **Origin header**: Must be set to `.mintlify.app` -2. **X-Forwarded-For**: Preserve client IP information -3. **X-Forwarded-Proto**: Preserve original protocol (HTTP/HTTPS) -4. **X-Real-IP**: Forward the real client IP address - -## Domain verification paths - -Your reverse proxy must allow these verification paths to pass through without modification: - -### Let's Encrypt verification - -``` -/.well-known/acme-challenge/* -``` - -### Vercel domain verification - -``` -/.well-known/vercel/* -``` - -These paths are essential for SSL certificate provisioning and domain ownership verification. Blocking or modifying requests to these paths will prevent proper setup. - ## Example configurations ### nginx @@ -134,100 +105,10 @@ server { } ``` -### Apache - -```apache - - ServerName yourdomain.com - - # Enable proxy module - ProxyPreserveHost Off - ProxyRequests Off - - # Let's Encrypt and Vercel verification paths - ProxyPassMatch ^/\.well-known/(acme-challenge|vercel)/(.*) https://your-subdomain.mintlify.app/.well-known/$1/$2 - ProxyPassReverseMatch ^/\.well-known/(acme-challenge|vercel)/(.*) https://your-subdomain.mintlify.app/.well-known/$1/$2 - - # Static assets - ProxyPassMatch ^/mintlify-assets/_next/static/(.*) https://your-subdomain.mintlify.app/mintlify-assets/_next/static/$1 - ProxyPassReverseMatch ^/mintlify-assets/_next/static/(.*) https://your-subdomain.mintlify.app/mintlify-assets/_next/static/$1 - - # All other paths - ProxyPass / https://your-subdomain.mintlify.app/ - ProxyPassReverse / https://your-subdomain.mintlify.app/ - - # Set required headers - ProxyPassReverse / https://your-subdomain.mintlify.app/ - RequestHeader set Origin "your-subdomain.mintlify.app" - RequestHeader set X-Forwarded-Proto "http" - -``` - -### HAProxy - -```haproxy -frontend docs_frontend - bind *:80 - - # Route verification paths - acl is_verification path_beg /.well-known/acme-challenge /.well-known/vercel - use_backend mintlify_backend if is_verification - - # Route static assets - acl is_static path_beg /mintlify-assets/_next/static - use_backend mintlify_backend if is_static - - # Default backend for all other requests - default_backend mintlify_backend - -backend mintlify_backend - server mintlify your-subdomain.mintlify.app:443 ssl verify none - - # Set required headers - http-request set-header Origin your-subdomain.mintlify.app - http-request set-header X-Forwarded-Proto http - http-request del-header Host -``` - -## Testing your configuration - -After configuring your reverse proxy, test these critical paths: - -### 1. Basic functionality - -```bash -curl -H "Host: yourdomain.com" http://your-proxy-server/ -``` - -### 2. Verification paths - -```bash -curl -H "Host: yourdomain.com" http://your-proxy-server/.well-known/vercel/test -curl -H "Host: yourdomain.com" http://your-proxy-server/.well-known/acme-challenge/test -``` - -### 3. Static assets - -```bash -curl -H "Host: yourdomain.com" http://your-proxy-server/mintlify-assets/_next/static/test.css -``` - -### 4. Header verification - -```bash -curl -v -H "Host: yourdomain.com" http://your-proxy-server/ 2>&1 | grep -E "(Origin|X-Forwarded|Host):" -``` + ## Common issues and troubleshooting -### Domain verification failures - -**Symptoms**: SSL certificate provisioning fails, domain verification errors - -**Cause**: Verification paths (`/.well-known/*`) are blocked or modified - -**Solution**: Ensure verification paths pass through without caching or modification - ### 404 Error Not Found **Symptoms**: Documentation loads but features don't work, API calls fail @@ -241,20 +122,12 @@ curl -v -H "Host: yourdomain.com" http://your-proxy-server/ 2>&1 | grep -E "(Ori ### Performance issues -**Symptoms**: Slow loading, repeated requests for static assets +**Symptoms**: Layout shift on pages. **Cause**: Incorrect caching configuration **Solution**: Enable caching only for `/mintlify-assets/_next/static/*` paths -### SSL/TLS errors - -**Symptoms**: Certificate errors, mixed content warnings - -**Cause**: Incorrect protocol forwarding - -**Solution**: Ensure `X-Forwarded-Proto` header reflects the original request protocol - ## Support limitations @@ -265,8 +138,4 @@ curl -v -H "Host: yourdomain.com" http://your-proxy-server/ 2>&1 | grep -E "(Ori - Broken authentication flows - Performance degradation - Analytics tracking issues - - -For production deployments requiring reverse proxy configurations, contact your account manager to discuss enterprise support options. - - \ No newline at end of file + \ No newline at end of file From 41d4dc2f7a77790c5d33d9600892828145737cbf Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Thu, 18 Sep 2025 09:12:07 -0700 Subject: [PATCH 09/22] move from `advanced` to `guides` --- docs.json | 2 +- {advanced => guides}/reverse-proxy.mdx | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename {advanced => guides}/reverse-proxy.mdx (100%) diff --git a/docs.json b/docs.json index 9f3d7ff73..dca944405 100644 --- a/docs.json +++ b/docs.json @@ -160,7 +160,7 @@ "advanced/subpath/cloudflare", "advanced/subpath/route53-cloudfront", "advanced/subpath/vercel", - "advanced/reverse-proxy", + "guides/reverse-proxy", "guides/csp-configuration" ] }, diff --git a/advanced/reverse-proxy.mdx b/guides/reverse-proxy.mdx similarity index 100% rename from advanced/reverse-proxy.mdx rename to guides/reverse-proxy.mdx From 88af300819e3eaeabdc2bc8ff94d5b1560fdb0ae Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Thu, 18 Sep 2025 09:21:38 -0700 Subject: [PATCH 10/22] copy edit --- guides/reverse-proxy.mdx | 26 ++++++++++++-------------- 1 file changed, 12 insertions(+), 14 deletions(-) diff --git a/guides/reverse-proxy.mdx b/guides/reverse-proxy.mdx index dbcf98d16..323b3632c 100644 --- a/guides/reverse-proxy.mdx +++ b/guides/reverse-proxy.mdx @@ -13,10 +13,10 @@ Configure your reverse proxy with these routing and caching rules: ### Route traffic to these paths **without caching**: -- `/.well-known/acme-challenge/*` -\> `.mintlify.app` -- `/.well-known/vercel/*` -\> `.mintlify.app` -- `/*` -\> `.minltify.app` -- `/` -\> `.mintlify.app` +- `/.well-known/acme-challenge/*` -> `.mintlify.app` +- `/.well-known/vercel/*` -> `.mintlify.app` +- `/*` -> `.mintlify.app` +- `/` -> `.mintlify.app` ### Route traffic to these paths **with caching**: @@ -31,8 +31,6 @@ Your reverse proxy must forward these headers: 3. **X-Forwarded-Proto**: Preserve original protocol (HTTP/HTTPS) 4. **X-Real-IP**: Forward the real client IP address -### Required headers - ```nginx # Example nginx configuration location / { @@ -52,7 +50,7 @@ location / { ``` - Ensurre that the `Host` header is not forwarded + Ensure that the `Host` header is not forwarded ## Example configurations @@ -66,8 +64,8 @@ server { # Let's Encrypt and Vercel verification paths location ~ ^/\.well-known/(acme-challenge|vercel)/ { - proxy_pass https://your-subdomain.mintlify.app; - proxy_set_header Origin your-subdomain.mintlify.app; + proxy_pass https://.mintlify.app; + proxy_set_header Origin .mintlify.app; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; @@ -79,8 +77,8 @@ server { # Static assets with caching location ~ ^/mintlify-assets/_next/static/ { - proxy_pass https://your-subdomain.mintlify.app; - proxy_set_header Origin your-subdomain.mintlify.app; + proxy_pass https://.mintlify.app; + proxy_set_header Origin .mintlify.app; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; @@ -92,8 +90,8 @@ server { # All other documentation paths location / { - proxy_pass https://your-subdomain.mintlify.app/; - proxy_set_header Origin your-subdomain.mintlify.app; + proxy_pass https://.mintlify.app/; + proxy_set_header Origin .mintlify.app; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; @@ -122,7 +120,7 @@ server { ### Performance issues -**Symptoms**: Layout shift on pages. +**Symptoms**: Slow page loads and layout shifts. **Cause**: Incorrect caching configuration From aaa37615309efeebd68053f0ed46f788b59882dd Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Thu, 18 Sep 2025 09:22:31 -0700 Subject: [PATCH 11/22] remove Custom from title --- guides/reverse-proxy.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guides/reverse-proxy.mdx b/guides/reverse-proxy.mdx index 323b3632c..6f968c58f 100644 --- a/guides/reverse-proxy.mdx +++ b/guides/reverse-proxy.mdx @@ -1,6 +1,6 @@ --- -title: "Custom reverse proxy" -description: "Configure a custom reverse proxy to serve Mintlify documentation" +title: "Reverse proxy" +description: "Configure a custom reverse proxy to serve your documentation" --- import Propagating from "/snippets/custom-subpath-propagating.mdx"; From e35941eccf6709c841df73a52c88a10e1ee9607d Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Thu, 18 Sep 2025 09:25:36 -0700 Subject: [PATCH 12/22] fix group casing --- docs.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs.json b/docs.json index dca944405..6d1555857 100644 --- a/docs.json +++ b/docs.json @@ -154,7 +154,7 @@ "settings/custom-404-page", "guides/monorepo", { - "group": "Custom Subdirectory", + "group": "Custom subdirectory", "icon": "folder", "pages": [ "advanced/subpath/cloudflare", @@ -165,7 +165,7 @@ ] }, { - "group": "Dashboard Access", + "group": "Dashboard access", "icon": "gauge", "pages": [ "advanced/dashboard/sso", From 997d22cc9dc43722a70b3d0b849a7f532986c1f1 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Thu, 18 Sep 2025 09:31:22 -0700 Subject: [PATCH 13/22] concision --- guides/reverse-proxy.mdx | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/guides/reverse-proxy.mdx b/guides/reverse-proxy.mdx index 6f968c58f..b0391800c 100644 --- a/guides/reverse-proxy.mdx +++ b/guides/reverse-proxy.mdx @@ -5,9 +5,13 @@ description: "Configure a custom reverse proxy to serve your documentation" import Propagating from "/snippets/custom-subpath-propagating.mdx"; -Custom reverse proxy configurations are **not officially supported** without an enterprise contract. To serve your Mintlify documentation through a custom reverse proxy, you need to configure specific routing rules, caching policies, and header forwarding to ensure proper functionality. + + Reverse proxy configurations are only supported for [Custom plans](https://mintlify.com/pricing?ref=reverse-proxy). + -## High-level overview +To serve your documentation through a custom reverse proxy, you must configure routing rules, caching policies, and header forwarding. + +## Overview Configure your reverse proxy with these routing and caching rules: @@ -18,7 +22,7 @@ Configure your reverse proxy with these routing and caching rules: - `/*` -> `.mintlify.app` - `/` -> `.mintlify.app` -### Route traffic to these paths **with caching**: +### Route traffic to these paths **with caching**: - `/mintlify-assets/_next/static/*` -\> `.mintlify.app/mintlify-assets/_next/static/` @@ -53,9 +57,7 @@ location / { Ensure that the `Host` header is not forwarded -## Example configurations - -### nginx +## Example nginxconfiguration ```nginx server { @@ -107,7 +109,7 @@ server { ## Common issues and troubleshooting -### 404 Error Not Found +### 404 error **Symptoms**: Documentation loads but features don't work, API calls fail @@ -129,7 +131,7 @@ server { ## Support limitations - Custom reverse proxy configurations are **not officially supported** without an enterprise contract. Common issues include: + Reverse proxy configurations are only supported for [Custom plans](https://mintlify.com/pricing?ref=reverse-proxy). Common issues include: - Domain verification failures - SSL certificate provisioning problems From 961daf999634dabc5fff8c8d47c3e5746761705f Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Thu, 18 Sep 2025 09:39:55 -0700 Subject: [PATCH 14/22] update header --- guides/reverse-proxy.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guides/reverse-proxy.mdx b/guides/reverse-proxy.mdx index b0391800c..9b86c5dd2 100644 --- a/guides/reverse-proxy.mdx +++ b/guides/reverse-proxy.mdx @@ -11,7 +11,7 @@ import Propagating from "/snippets/custom-subpath-propagating.mdx"; To serve your documentation through a custom reverse proxy, you must configure routing rules, caching policies, and header forwarding. -## Overview +## Routing configuration Configure your reverse proxy with these routing and caching rules: @@ -138,4 +138,4 @@ server { - Broken authentication flows - Performance degradation - Analytics tracking issues - \ No newline at end of file + From a6fdb4be494f4eea2d380246282b50526def25ac Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Thu, 18 Sep 2025 09:41:52 -0700 Subject: [PATCH 15/22] replace lists with table --- guides/reverse-proxy.mdx | 17 +++++++---------- 1 file changed, 7 insertions(+), 10 deletions(-) diff --git a/guides/reverse-proxy.mdx b/guides/reverse-proxy.mdx index 9b86c5dd2..19bc37b4d 100644 --- a/guides/reverse-proxy.mdx +++ b/guides/reverse-proxy.mdx @@ -15,16 +15,13 @@ To serve your documentation through a custom reverse proxy, you must configure r Configure your reverse proxy with these routing and caching rules: -### Route traffic to these paths **without caching**: - -- `/.well-known/acme-challenge/*` -> `.mintlify.app` -- `/.well-known/vercel/*` -> `.mintlify.app` -- `/*` -> `.mintlify.app` -- `/` -> `.mintlify.app` - -### Route traffic to these paths **with caching**: - -- `/mintlify-assets/_next/static/*` -\> `.mintlify.app/mintlify-assets/_next/static/` +| Path | Destination | Caching | +|------|-------------|---------| +| `/.well-known/acme-challenge/*` | `.mintlify.app` | No cache | +| `/.well-known/vercel/*` | `.mintlify.app` | No cache | +| `/*` | `.mintlify.app` | No cache | +| `/` | `.mintlify.app` | No cache | +| `/mintlify-assets/_next/static/*` | `.mintlify.app/mintlify-assets/_next/static/` | Cache enabled | ## Required header configuration From aac35ccb5e97ec8533e3af1eb3b9426f6a1f3486 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Thu, 18 Sep 2025 09:49:29 -0700 Subject: [PATCH 16/22] more active language --- guides/reverse-proxy.mdx | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/guides/reverse-proxy.mdx b/guides/reverse-proxy.mdx index 19bc37b4d..fe15361d6 100644 --- a/guides/reverse-proxy.mdx +++ b/guides/reverse-proxy.mdx @@ -13,7 +13,7 @@ To serve your documentation through a custom reverse proxy, you must configure r ## Routing configuration -Configure your reverse proxy with these routing and caching rules: +Proxy these paths to your Mintlify subdomain with the specified caching policies: | Path | Destination | Caching | |------|-------------|---------| @@ -25,12 +25,16 @@ Configure your reverse proxy with these routing and caching rules: ## Required header configuration -Your reverse proxy must forward these headers: +Configure your reverse proxy with these header requirements: -1. **Origin header**: Must be set to `.mintlify.app` -2. **X-Forwarded-For**: Preserve client IP information -3. **X-Forwarded-Proto**: Preserve original protocol (HTTP/HTTPS) -4. **X-Real-IP**: Forward the real client IP address +- **Origin**: Set to `.mintlify.app` +- **X-Forwarded-For**: Preserve client IP information +- **X-Forwarded-Proto**: Preserve original protocol (HTTP/HTTPS) +- **X-Real-IP**: Forward the real client IP address + + + Ensure that the `Host` header is not forwarded + ```nginx # Example nginx configuration @@ -50,10 +54,6 @@ location / { } ``` - - Ensure that the `Host` header is not forwarded - - ## Example nginxconfiguration ```nginx From 5bbcbb8535b5975282ba360e40e844027614f96d Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Thu, 18 Sep 2025 09:50:42 -0700 Subject: [PATCH 17/22] remove redundant example --- guides/reverse-proxy.mdx | 20 +------------------- 1 file changed, 1 insertion(+), 19 deletions(-) diff --git a/guides/reverse-proxy.mdx b/guides/reverse-proxy.mdx index fe15361d6..b2e7a8a8a 100644 --- a/guides/reverse-proxy.mdx +++ b/guides/reverse-proxy.mdx @@ -36,25 +36,7 @@ Configure your reverse proxy with these header requirements: Ensure that the `Host` header is not forwarded -```nginx -# Example nginx configuration -location / { - proxy_pass https://.mintlify.app/; - - # CRITICAL: Set the correct origin header - proxy_set_header Origin .mintlify.app; - - # Forward client information - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $scheme; - - # DO NOT forward the Host header - this will break functionality - # proxy_set_header Host $host; # ← DO NOT INCLUDE THIS LINE -} -``` - -## Example nginxconfiguration +## Example nginx configuration ```nginx server { From 25b11e2297224d1498a8102f04734025697dc5df Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Thu, 18 Sep 2025 09:56:19 -0700 Subject: [PATCH 18/22] update placeholder --- guides/reverse-proxy.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/reverse-proxy.mdx b/guides/reverse-proxy.mdx index b2e7a8a8a..91635dfe3 100644 --- a/guides/reverse-proxy.mdx +++ b/guides/reverse-proxy.mdx @@ -41,7 +41,7 @@ Configure your reverse proxy with these header requirements: ```nginx server { listen 80; - server_name yourdomain.com; + server_name .com; # Let's Encrypt and Vercel verification paths location ~ ^/\.well-known/(acme-challenge|vercel)/ { From 35404eea2d963cf9acdf65b982949ab913e1cff4 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Thu, 18 Sep 2025 09:57:53 -0700 Subject: [PATCH 19/22] remove propagating snippet --- guides/reverse-proxy.mdx | 4 ---- 1 file changed, 4 deletions(-) diff --git a/guides/reverse-proxy.mdx b/guides/reverse-proxy.mdx index 91635dfe3..30bc86563 100644 --- a/guides/reverse-proxy.mdx +++ b/guides/reverse-proxy.mdx @@ -3,8 +3,6 @@ title: "Reverse proxy" description: "Configure a custom reverse proxy to serve your documentation" --- -import Propagating from "/snippets/custom-subpath-propagating.mdx"; - Reverse proxy configurations are only supported for [Custom plans](https://mintlify.com/pricing?ref=reverse-proxy). @@ -84,8 +82,6 @@ server { } ``` - - ## Common issues and troubleshooting ### 404 error From 71e0cb6e9a3c03efa4a19d5635dabb847250b841 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Thu, 18 Sep 2025 10:05:06 -0700 Subject: [PATCH 20/22] copy edit troubleshooting --- guides/reverse-proxy.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/guides/reverse-proxy.mdx b/guides/reverse-proxy.mdx index 30bc86563..626dc5bfa 100644 --- a/guides/reverse-proxy.mdx +++ b/guides/reverse-proxy.mdx @@ -82,13 +82,13 @@ server { } ``` -## Common issues and troubleshooting +## Troubleshooting ### 404 error -**Symptoms**: Documentation loads but features don't work, API calls fail +**Symptoms**: Documentation loads, but features don't work. API calls fail. -**Cause**: Host header is being forwarded or Origin header is missing +**Cause**: `Host` header is being forwarded or `Origin` header is missing. **Solution**: @@ -99,9 +99,9 @@ server { **Symptoms**: Slow page loads and layout shifts. -**Cause**: Incorrect caching configuration +**Cause**: Incorrect caching configuration. -**Solution**: Enable caching only for `/mintlify-assets/_next/static/*` paths +**Solution**: Enable caching only for `/mintlify-assets/_next/static/*` paths. ## Support limitations From 9f3126ac7559fafafb72be5feff1d8c7aebd534d Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Thu, 18 Sep 2025 10:09:35 -0700 Subject: [PATCH 21/22] make limitations more solutions-oriented --- guides/reverse-proxy.mdx | 14 ++------------ 1 file changed, 2 insertions(+), 12 deletions(-) diff --git a/guides/reverse-proxy.mdx b/guides/reverse-proxy.mdx index 626dc5bfa..63dd2be5a 100644 --- a/guides/reverse-proxy.mdx +++ b/guides/reverse-proxy.mdx @@ -9,6 +9,8 @@ description: "Configure a custom reverse proxy to serve your documentation" To serve your documentation through a custom reverse proxy, you must configure routing rules, caching policies, and header forwarding. +When you implement a reverse proxy, monitor for potential issues with domain verification, SSL certificate provisioning, authentication flows, performance, and analytics tracking. + ## Routing configuration Proxy these paths to your Mintlify subdomain with the specified caching policies: @@ -102,15 +104,3 @@ server { **Cause**: Incorrect caching configuration. **Solution**: Enable caching only for `/mintlify-assets/_next/static/*` paths. - -## Support limitations - - - Reverse proxy configurations are only supported for [Custom plans](https://mintlify.com/pricing?ref=reverse-proxy). Common issues include: - - - Domain verification failures - - SSL certificate provisioning problems - - Broken authentication flows - - Performance degradation - - Analytics tracking issues - From 21824104855b23cbbf8adef12dbd69d7fc118b13 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Thu, 18 Sep 2025 15:24:43 -0700 Subject: [PATCH 22/22] update example config --- guides/reverse-proxy.mdx | 61 +++++++++++++++++++++++++++++----------- 1 file changed, 44 insertions(+), 17 deletions(-) diff --git a/guides/reverse-proxy.mdx b/guides/reverse-proxy.mdx index 63dd2be5a..8b033e68b 100644 --- a/guides/reverse-proxy.mdx +++ b/guides/reverse-proxy.mdx @@ -19,18 +19,19 @@ Proxy these paths to your Mintlify subdomain with the specified caching policies |------|-------------|---------| | `/.well-known/acme-challenge/*` | `.mintlify.app` | No cache | | `/.well-known/vercel/*` | `.mintlify.app` | No cache | +| `/mintlify-assets/_next/static/*` | `.mintlify.app` | Cache enabled | | `/*` | `.mintlify.app` | No cache | | `/` | `.mintlify.app` | No cache | -| `/mintlify-assets/_next/static/*` | `.mintlify.app/mintlify-assets/_next/static/` | Cache enabled | ## Required header configuration Configure your reverse proxy with these header requirements: -- **Origin**: Set to `.mintlify.app` -- **X-Forwarded-For**: Preserve client IP information -- **X-Forwarded-Proto**: Preserve original protocol (HTTP/HTTPS) -- **X-Real-IP**: Forward the real client IP address +- **Origin**: Contains the target subdomain `.mintlify.app` +- **X-Forwarded-For**: Preserves client IP information +- **X-Forwarded-Proto**: Preserves original protocol (HTTP/HTTPS) +- **X-Real-IP**: Forwards the real client IP address +- **User-Agent**: Forwards the user agent Ensure that the `Host` header is not forwarded @@ -42,20 +43,33 @@ Configure your reverse proxy with these header requirements: server { listen 80; server_name .com; - - # Let's Encrypt and Vercel verification paths - location ~ ^/\.well-known/(acme-challenge|vercel)/ { + + # Let's Encrypt verification paths + location ~ ^/\.well-known/acme-challenge/ { + proxy_pass https://.mintlify.app; + proxy_set_header Origin .mintlify.app; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header User-Agent $http_user_agent; + + # Disable caching for verification paths + add_header Cache-Control "no-cache, no-store, must-revalidate"; + } + + # Vercel verification paths + location ~ ^/\.well-known/vercel/ { proxy_pass https://.mintlify.app; proxy_set_header Origin .mintlify.app; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; - + proxy_set_header User-Agent $http_user_agent; + # Disable caching for verification paths - proxy_cache off; add_header Cache-Control "no-cache, no-store, must-revalidate"; } - + # Static assets with caching location ~ ^/mintlify-assets/_next/static/ { proxy_pass https://.mintlify.app; @@ -63,22 +77,35 @@ server { proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; - + proxy_set_header User-Agent $http_user_agent; + # Enable caching for static assets - proxy_cache_valid 200 1d; add_header Cache-Control "public, max-age=86400"; } - + + # Root path + location = / { + proxy_pass https://.mintlify.app; + proxy_set_header Origin .mintlify.app; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header User-Agent $http_user_agent; + + # Disable caching for dynamic content + add_header Cache-Control "no-cache, no-store, must-revalidate"; + } + # All other documentation paths location / { - proxy_pass https://.mintlify.app/; + proxy_pass https://.mintlify.app; proxy_set_header Origin .mintlify.app; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; - + proxy_set_header User-Agent $http_user_agent; + # Disable caching for dynamic content - proxy_cache off; add_header Cache-Control "no-cache, no-store, must-revalidate"; } }