Reverse proxy setup

Create the Worker

Create a Cloudflare Worker that intercepts requests to your docs subpath and proxies them to Fern:

1
const SUBPATH = "/docs";
2
const FERN_HOST = "mydomain.com";
3
4
export default {
5
  async fetch(request) {
6
    const url = new URL(request.url);
7
8
    if (
9
      url.pathname !== SUBPATH &&
10
      !url.pathname.startsWith(`${SUBPATH}/`)
11
    ) {
12
      return new Response("Not found", { status: 404 });
13
    }
14
15
    const upstreamUrl = new URL(request.url);
16
    upstreamUrl.protocol = "https:";
17
    upstreamUrl.hostname = "app.buildwithfern.com";
18
    upstreamUrl.port = "";
19
20
    const proxiedRequest = new Request(upstreamUrl, request);
21
    proxiedRequest.headers.set("x-fern-host", FERN_HOST);
22
23
    return fetch(proxiedRequest);
24
  },
25
};

Replace SUBPATH and FERN_HOST with your subpath and bare domain.

Attach the Worker to a route

In the Cloudflare dashboard under Workers Routes, attach the Worker to a route pattern like mydomain.com/docs/*.

Check for conflicting cache rules

The Worker forwards Fern’s Cache-Control header, so caching works automatically. In the Cloudflare dashboard, confirm that no Page Rule or Cache Rule sets “Cache Level: Cache Everything” for /docs* — if one exists, remove it or override it with “Cache Level: Bypass.”

Add a Fern origin

In your CloudFront distribution, go to Origins and create a new origin:

Under Add custom header, add:

Replace mydomain.com with your bare domain (without the subpath).

Create a cache behavior for your docs path

Go to Behaviors and create a new behavior:

AllViewerExceptHostHeader forwards all viewer headers, query strings, and cookies to the origin while letting CloudFront set the Host header to app.buildwithfern.com. This is required — Fern’s origin uses the Host header for routing and rejects requests with an unrecognized host.

Verify the behavior order

CloudFront evaluates behaviors in order. Ensure your /docs* behavior appears above the default (*) behavior so docs requests are routed to Fern’s origin rather than your primary site.

Add a rewrite rule

In netlify.toml (or _redirects):

1
[[redirects]]
2
  from = "/docs/*"
3
  to = "https://app.buildwithfern.com/docs/:splat"
4
  status = 200
5
  force = true
6
7
  [redirects.headers]
8
    x-fern-host = "mydomain.com"

Disable rate limiting for the docs path

Fern revalidates your docs site by warming page caches with concurrent requests. Netlify’s traffic rules can interpret this as abusive traffic and block the requests, causing revalidation to fail.

If you have rate limiting enabled under Security > Traffic rules in the Netlify dashboard, add a rule that excludes your docs subpath (/docs/*) from rate limiting.

Check the proxy timeout

Fern’s revalidation endpoint streams a long-running response while warming page caches. Netlify limits proxy rewrite requests to 26 seconds, which can terminate the stream before warming completes on sites with more than a few hundred pages.

If revalidation consistently fails with a “terminated” status, this timeout is the most likely cause. Contact Netlify support to request a timeout increase for your site, or reach out to Fern support for alternative warming options.

Add a route with a transform

Use a route with a transform rule to rewrite the path and set x-fern-host in one step:

1
{
2
  "$schema": "https://openapi.vercel.sh/vercel.json",
3
  "routes": [
4
    {
5
      "src": "/docs(/.*)?",
6
      "dest": "https://app.buildwithfern.com/docs$1",
7
      "transforms": [
8
        {
9
          "type": "request.headers",
10
          "op": "set",
11
          "target": { "key": "x-fern-host" },
12
          "args": "mydomain.com"
13
        }
14
      ]
15
    }
16
  ]
17
}

Add a location block

1
location /docs {
2
    proxy_pass https://app.buildwithfern.com;
3
    proxy_set_header Host app.buildwithfern.com;
4
    proxy_set_header x-fern-host mydomain.com;
5
    proxy_set_header X-Real-IP $remote_addr;
6
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
7
    proxy_set_header X-Forwarded-Proto $scheme;
8
    proxy_ssl_server_name on;
9
10
    # Prevent encoding issues with Brotli responses
11
    proxy_set_header Accept-Encoding "gzip, deflate";
12
13
    # Do not cache HTML
14
    proxy_no_cache 1;
15
    proxy_cache_bypass 1;
16
    add_header Cache-Control "public, max-age=0, must-revalidate" always;
17
}

Add a routing rule

In a Site Delivery or Ion property, add a rule matching path /docs*:

• Origin Server: app.buildwithfern.com
• Forward Host Header: Origin Hostname

Add a Modify Outgoing Request Header behavior:

Disable caching on the rule

Add a Caching behavior to the same rule:

Alternatively, set Honor Origin Cache-Control to Yes so Akamai respects Fern’s Cache-Control: public, max-age=0, must-revalidate header.

Add to your Caddyfile

mydomain.com {
    handle /docs* {
        reverse_proxy https://app.buildwithfern.com {
            header_up Host app.buildwithfern.com
            header_up x-fern-host mydomain.com
        }
    }
}