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"

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

1
mydomain.com {
2
    handle /docs* {
3
        reverse_proxy https://app.buildwithfern.com {
4
            header_up Host app.buildwithfern.com
5
            header_up x-fern-host mydomain.com
6
        }
7
    }
8
}