Skip to content

Commit 7c71d9c

Browse files
mintlify[bot]ethanpalm
mintlify[bot]
and
ethanpalm
authored
Added custom reverse proxy configurartion. (#1200)
* Update advanced/reverse-proxy.mdx * Update docs.json * Documentation edits made through Mintlify web editor * Update advanced/reverse-proxy.mdx * Update advanced/reverse-proxy.mdx * Update advanced/reverse-proxy.mdx * Documentation edits made through Mintlify web editor * Documentation edits made through Mintlify web editor * move from `advanced` to `guides` * copy edit * remove Custom from title * fix group casing * concision * update header * replace lists with table * more active language * remove redundant example * update placeholder * remove propagating snippet * copy edit troubleshooting * make limitations more solutions-oriented * update example config --------- Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> Co-authored-by: Ethan Palm <[email protected]>
1 parent c6b60fd commit 7c71d9c

File tree

2 files changed

+137
-3
lines changed

2 files changed

+137
-3
lines changed

‎docs.json‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -154,17 +154,18 @@
154154
"settings/custom-404-page",
155155
"guides/monorepo",
156156
{
157-
"group": "Custom Subdirectory",
157+
"group": "Custom subdirectory",
158158
"icon": "folder",
159159
"pages": [
160160
"advanced/subpath/cloudflare",
161161
"advanced/subpath/route53-cloudfront",
162162
"advanced/subpath/vercel",
163+
"guides/reverse-proxy",
163164
"guides/csp-configuration"
164165
]
165166
},
166167
{
167-
"group": "Dashboard Access",
168+
"group": "Dashboard access",
168169
"icon": "gauge",
169170
"pages": [
170171
"advanced/dashboard/sso",
@@ -551,4 +552,4 @@
551552
"publicApiKey": "pk_76a6caa274e800f3ceff0b2bc6b9b9d82ab8"
552553
}
553554
}
554-
}
555+
}

‎guides/reverse-proxy.mdx‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
---
2+
title: "Reverse proxy"
3+
description: "Configure a custom reverse proxy to serve your documentation"
4+
---
5+
6+
<Note>
7+
Reverse proxy configurations are only supported for [Custom plans](https://mintlify.com/pricing?ref=reverse-proxy).
8+
</Note>
9+
10+
To serve your documentation through a custom reverse proxy, you must configure routing rules, caching policies, and header forwarding.
11+
12+
When you implement a reverse proxy, monitor for potential issues with domain verification, SSL certificate provisioning, authentication flows, performance, and analytics tracking.
13+
14+
## Routing configuration
15+
16+
Proxy these paths to your Mintlify subdomain with the specified caching policies:
17+
18+
| Path | Destination | Caching |
19+
|------|-------------|---------|
20+
| `/.well-known/acme-challenge/*` | `<your-subdomain>.mintlify.app` | No cache |
21+
| `/.well-known/vercel/*` | `<your-subdomain>.mintlify.app` | No cache |
22+
| `/mintlify-assets/_next/static/*` | `<your-subdomain>.mintlify.app` | Cache enabled |
23+
| `/*` | `<your-subdomain>.mintlify.app` | No cache |
24+
| `/` | `<your-subdomain>.mintlify.app` | No cache |
25+
26+
## Required header configuration
27+
28+
Configure your reverse proxy with these header requirements:
29+
30+
- **Origin**: Contains the target subdomain `<your-subdomain>.mintlify.app`
31+
- **X-Forwarded-For**: Preserves client IP information
32+
- **X-Forwarded-Proto**: Preserves original protocol (HTTP/HTTPS)
33+
- **X-Real-IP**: Forwards the real client IP address
34+
- **User-Agent**: Forwards the user agent
35+
36+
<Warning>
37+
Ensure that the `Host` header is not forwarded
38+
</Warning>
39+
40+
## Example nginx configuration
41+
42+
```nginx
43+
server {
44+
listen 80;
45+
server_name <your-domain>.com;
46+
47+
# Let's Encrypt verification paths
48+
location ~ ^/\.well-known/acme-challenge/ {
49+
proxy_pass https://<your-subdomain>.mintlify.app;
50+
proxy_set_header Origin <your-subdomain>.mintlify.app;
51+
proxy_set_header X-Real-IP $remote_addr;
52+
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
53+
proxy_set_header X-Forwarded-Proto $scheme;
54+
proxy_set_header User-Agent $http_user_agent;
55+
56+
# Disable caching for verification paths
57+
add_header Cache-Control "no-cache, no-store, must-revalidate";
58+
}
59+
60+
# Vercel verification paths
61+
location ~ ^/\.well-known/vercel/ {
62+
proxy_pass https://<your-subdomain>.mintlify.app;
63+
proxy_set_header Origin <your-subdomain>.mintlify.app;
64+
proxy_set_header X-Real-IP $remote_addr;
65+
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
66+
proxy_set_header X-Forwarded-Proto $scheme;
67+
proxy_set_header User-Agent $http_user_agent;
68+
69+
# Disable caching for verification paths
70+
add_header Cache-Control "no-cache, no-store, must-revalidate";
71+
}
72+
73+
# Static assets with caching
74+
location ~ ^/mintlify-assets/_next/static/ {
75+
proxy_pass https://<your-subdomain>.mintlify.app;
76+
proxy_set_header Origin <your-subdomain>.mintlify.app;
77+
proxy_set_header X-Real-IP $remote_addr;
78+
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
79+
proxy_set_header X-Forwarded-Proto $scheme;
80+
proxy_set_header User-Agent $http_user_agent;
81+
82+
# Enable caching for static assets
83+
add_header Cache-Control "public, max-age=86400";
84+
}
85+
86+
# Root path
87+
location = / {
88+
proxy_pass https://<your-subdomain>.mintlify.app;
89+
proxy_set_header Origin <your-subdomain>.mintlify.app;
90+
proxy_set_header X-Real-IP $remote_addr;
91+
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
92+
proxy_set_header X-Forwarded-Proto $scheme;
93+
proxy_set_header User-Agent $http_user_agent;
94+
95+
# Disable caching for dynamic content
96+
add_header Cache-Control "no-cache, no-store, must-revalidate";
97+
}
98+
99+
# All other documentation paths
100+
location / {
101+
proxy_pass https://<your-subdomain>.mintlify.app;
102+
proxy_set_header Origin <your-subdomain>.mintlify.app;
103+
proxy_set_header X-Real-IP $remote_addr;
104+
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
105+
proxy_set_header X-Forwarded-Proto $scheme;
106+
proxy_set_header User-Agent $http_user_agent;
107+
108+
# Disable caching for dynamic content
109+
add_header Cache-Control "no-cache, no-store, must-revalidate";
110+
}
111+
}
112+
```
113+
114+
## Troubleshooting
115+
116+
### 404 error
117+
118+
**Symptoms**: Documentation loads, but features don't work. API calls fail.
119+
120+
**Cause**: `Host` header is being forwarded or `Origin` header is missing.
121+
122+
**Solution**:
123+
124+
- Remove `Host` header forwarding
125+
- Set `Origin` header to `<your-subdomain>.mintlify.app`
126+
127+
### Performance issues
128+
129+
**Symptoms**: Slow page loads and layout shifts.
130+
131+
**Cause**: Incorrect caching configuration.
132+
133+
**Solution**: Enable caching only for `/mintlify-assets/_next/static/*` paths.

0 commit comments

Comments
 (0)