Skip to content

reverse-proxy.mdx

Latest commit

 

History

History
405 lines (322 loc) · 17.3 KB

reverse-proxy.mdx

File metadata and controls

405 lines (322 loc) · 17.3 KB
Raw
title Reverse proxy
description Configure a custom reverse proxy with Nginx, Apache, or Caddy to serve your Mintlify documentation at a subpath on your own domain.
keywords
reverse proxy configuration
nginx
proxy routing
header forwarding

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.

Choose your deployment approach

Mintlify supports two reverse proxy configurations depending on your subpath requirements.

  • Host at /docs: Use mintlify.cc as the proxy target. Enable the Host at /docs toggle on the Custom domain setup page in your dashboard. This is a simpler configuration with fewer routes.
  • Custom subpath: Use mintlify.app as the proxy target. This approach supports any subpath and requires additional routing rules.

Host at /docs subpath

Use this configuration when you want to serve documentation at the /docs path on your domain.

Before configuring your reverse proxy:

  1. Navigate to Custom domain setup in your dashboard.
  2. Enable the Host at /docs toggle.
  3. Enter your domain and click Add domain.
When you enable **Host at `/docs`**, your canonical docs URL becomes `.mintlify.cc`. Cache invalidation stops on `mintlify.app`, and you must proxy to `mintlify.cc` for updates to appear.

Routing configuration

Proxy these paths to your Mintlify subdomain:

Path Destination Caching
/docs <your-subdomain>.mintlify.cc/docs No cache
/docs/* <your-subdomain>.mintlify.cc/docs No cache
/.well-known/vercel/* <your-subdomain>.mintlify.cc No cache
/.well-known/skills/* (optional) <your-subdomain>.mintlify.cc/docs No cache
/.well-known/agent-skills/* (optional) <your-subdomain>.mintlify.cc/docs No cache
/skill.md (optional) <your-subdomain>.mintlify.cc/docs No cache
/llms.txt (optional) <your-subdomain>.mintlify.cc/docs No cache
/llms-full.txt (optional) <your-subdomain>.mintlify.cc/docs No cache

The /.well-known/skills/*, /.well-known/agent-skills/*, /skill.md, /llms.txt, and /llms-full.txt routes are optional. Include them only if you want to serve AI files at root paths like your-domain.com/llms.txt instead of under your docs subpath like your-domain.com/docs/llms.txt.

Required header configuration

Configure your reverse proxy with these header requirements:

  • Origin: Contains the target subdomain <your-subdomain>.mintlify.cc
  • 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.

Example nginx configuration

server {
    listen 80;
    server_name <your-domain>.com;

    # Vercel verification paths
    location ~ ^/\.well-known/vercel/ {
        proxy_pass https://<your-subdomain>.mintlify.cc;
        proxy_set_header Origin <your-subdomain>.mintlify.cc;
        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;

        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }

    # AI skills paths
    location ^~ /.well-known/skills/ {
        proxy_pass https://<your-subdomain>.mintlify.cc/docs;
        proxy_set_header Origin <your-subdomain>.mintlify.cc;
        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;

        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }

    # Agent-skills discovery paths
    location ^~ /.well-known/agent-skills/ {
        proxy_pass https://<your-subdomain>.mintlify.cc/docs;
        proxy_set_header Origin <your-subdomain>.mintlify.cc;
        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;

        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }

    # Skill manifest (optional)
    location = /skill.md {
        proxy_pass https://<your-subdomain>.mintlify.cc/docs;
        proxy_set_header Origin <your-subdomain>.mintlify.cc;
        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;

        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }

    # LLM index files (optional)
    location = /llms.txt {
        proxy_pass https://<your-subdomain>.mintlify.cc/docs;
        proxy_set_header Origin <your-subdomain>.mintlify.cc;
        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;

        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }

    location = /llms-full.txt {
        proxy_pass https://<your-subdomain>.mintlify.cc/docs;
        proxy_set_header Origin <your-subdomain>.mintlify.cc;
        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;

        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }

    # Documentation root
    location = /docs {
        proxy_pass https://<your-subdomain>.mintlify.cc/docs;
        proxy_set_header Origin <your-subdomain>.mintlify.cc;
        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;

        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }

    # All documentation paths
    location /docs/ {
        proxy_pass https://<your-subdomain>.mintlify.cc/docs/;
        proxy_set_header Origin <your-subdomain>.mintlify.cc;
        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;

        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }
}

Custom subpath

Reverse proxy configurations for custom subpaths are only supported for [Enterprise plans](https://mintlify.com/pricing?ref=reverse-proxy).

When you need a subpath other than /docs (such as /help or /resources), use the following routing configuration.

Proxy these paths to your Mintlify subdomain with the specified caching policies:

Path Destination Caching
/.well-known/vercel/* <your-subdomain>.mintlify.app No cache
/.well-known/skills/* <your-subdomain>.mintlify.app No cache
/.well-known/agent-skills/* <your-subdomain>.mintlify.app No cache
/skill.md <your-subdomain>.mintlify.app No cache
/llms.txt <your-subdomain>.mintlify.app No cache
/llms-full.txt <your-subdomain>.mintlify.app No cache
/mintlify-assets/_next/static/* <your-subdomain>.mintlify.app Cache enabled
/_mintlify/* <your-subdomain>.mintlify.app No cache
/* <your-subdomain>.mintlify.app No cache
/ <your-subdomain>.mintlify.app No cache
Mintlify serves `llms.txt`, `llms-full.txt`, and `skill.md` at the root path. If your docs live under a subpath (such as `/help`), you can also serve these files under that subpath (for example, `/help/llms.txt`). To do this, add location blocks that rewrite the subpath to the root path. See the nginx example below for both patterns.

Required header configuration

Configure your reverse proxy with these header requirements:

  • Origin: Contains the target subdomain <your-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

Example nginx configuration

server {
    listen 80;
    server_name <your-domain>.com;

    # Vercel verification paths
    location ~ ^/\.well-known/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;
        proxy_set_header User-Agent $http_user_agent;

        # Disable caching for verification paths
        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }

    # AI skills paths
    location ^~ /.well-known/skills/ {
        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;
        proxy_set_header User-Agent $http_user_agent;

        # Disable caching for verification paths
        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }

    # Agent-skills discovery paths
    location ^~ /.well-known/agent-skills/ {
        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;
        proxy_set_header User-Agent $http_user_agent;

        # Disable caching for agent-skills paths
        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }

    # Skill manifest
    location = /skill.md {
        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;
        proxy_set_header User-Agent $http_user_agent;

        # Disable caching for skill manifest
        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }

    # LLM index files
    location = /llms.txt {
        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;
        proxy_set_header User-Agent $http_user_agent;

        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }

    location = /llms-full.txt {
        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;
        proxy_set_header User-Agent $http_user_agent;

        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }

    # Optional: Serve AI files under your subpath with path rewriting.
    # Replace "/help" with your subpath. These blocks rewrite the
    # subpath so Mintlify receives the root path it expects.
    #
    # location = /help/llms.txt {
    #     proxy_pass https://<your-subdomain>.mintlify.app/llms.txt;
    #     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;
    #     add_header Cache-Control "no-cache, no-store, must-revalidate";
    # }
    #
    # location = /help/llms-full.txt {
    #     proxy_pass https://<your-subdomain>.mintlify.app/llms-full.txt;
    #     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;
    #     add_header Cache-Control "no-cache, no-store, must-revalidate";
    # }
    #
    # location = /help/skill.md {
    #     proxy_pass https://<your-subdomain>.mintlify.app/skill.md;
    #     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;
    #     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;
        proxy_set_header User-Agent $http_user_agent;

        # Enable caching for static assets
        add_header Cache-Control "public, max-age=86400";
    }

    # Mintlify-specific paths
    location ~ ^/_mintlify/ {
        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;
        proxy_set_header User-Agent $http_user_agent;

        # Disable caching for Mintlify paths
        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }

    # Root path
    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;
        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://<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;
        proxy_set_header User-Agent $http_user_agent;

        # Disable caching for dynamic content
        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }
}

Troubleshooting

Changes not appearing

Symptoms: You publish documentation updates, but the changes don't appear on your site.

Cause: You have Host at /docs enabled in your dashboard but your reverse proxy points to mintlify.app instead of mintlify.cc.

Solution: Update your reverse proxy configuration to point to <your-subdomain>.mintlify.cc instead of <your-subdomain>.mintlify.app.

404 error

Symptoms: Documentation loads, but features don't work. API calls fail.

Cause: The reverse proxy forwards the Host header or the Origin header is missing.

Solution:

  • Remove Host header forwarding
  • Set Origin header to your Mintlify subdomain (mintlify.cc for a /docs subpath or mintlify.app for a different subpath)

Performance issues

Symptoms: Slow page loads and layout shifts.

Cause: Incorrect caching configuration.

Solution: For custom subpath configurations, enable caching only for /mintlify-assets/_next/static/* paths. The /docs subpath configuration handles caching automatically.