Set up self-hosted documentation

Enterprise feature

This feature is available only for the Enterprise plan. To get started, reach out to support@buildwithfern.com.

Prerequisites

Before setting up self-hosted documentation, ensure you have:

Docker installed on your system
Access to your Fern project’s fern/ directory
A Docker Hub account (for accessing the private image)

Setup instructions

Request Access to the Docker Image

The self-hosted documentation runs on a private Docker image: fernapi/fern-self-hosted

Contact Fern Support and provide your Docker Hub username to the Fern team. Fern will allowlist your account to download the private image, and provide you with the latest tag.

Download the Docker Image

Once your account is allowlisted, download the latest image:

$ docker pull fernapi/fern-self-hosted:<latest-tag>

Do not use fernapi/fern-self-hosted:latest as it may not contain the most recent version. Always use the specific latest tag provided by Fern.

You can verify the image is available in your Docker daemon:

$ docker images | grep fernapi/fern-self-hosted

Create a Dockerfile

In the directory containing your fern/ folder, create a new Dockerfile with the following content:

<your-docker-file-name>

1 FROM fernapi/fern-self-hosted:<latest-tag>
2 
3 COPY fern/ /fern/
4 
5 RUN fern-generate

Replace <latest-tag> with the actual tag used in the previous step.

fern-generate processes your documentation at build time, enabling faster container startup, air-gapped deployment, and a smaller attack surface. You can alternatively defer generation to runtime.

Build Your Custom Docker Image

Build your custom Docker image using the Dockerfile:

$ docker build -f <your-docker-file-name> -t <your-image-name> <path-to-dockerfile>

Example:

$ docker build -f Dockerfile -t self-hosted-docs .

Run the Documentation

Start your self-hosted documentation:

$ docker run -p <port-number>:3000 <your-image-name>

The documentation will be available at localhost:<port-number>.

Configure Custom Domain

Your documentation will be published to the domain specified in your docs.yml file. For example:

1 instances:
2   - url: example-org.docs.buildwithfern.com
3     custom-domain: docs.plantstore.dev

Deploy the Documentation

You can now deploy the image to your own infrastructure, allowing you to host the documentation on your own domain.

Environment variables

Configure the self-hosted container’s behavior by setting environment variables in your Dockerfile or Kubernetes deployment.

General

Variable	Description	Default
`FERN_LOG_LEVEL`	Log level for the Fern CLI during docs generation. Options: `debug`, `info`, `warn`, `error`.	`debug`
`NODE_MEMORY_LIMIT`	Node.js heap size in MB for the Next.js server. Increase for large documentation sites with many API versions.	`4096`
`NEXT_PUBLIC_BASE_PATH`	Serve the documentation from a sub-path instead of root. The value must start with `/` and have no trailing slash (e.g., `/docs`). See Base path for details.	none (serves from `/`)

Cache warmup

The container can pre-fetch all pages on startup to ensure the first real user request is fast.

Variable	Description	Default
`WARMUP`	Set to `true` to enable cache warmup on startup. Runs in the background and doesn’t block container readiness.	`false`
`WARMUP_TIMEOUT`	Timeout in seconds for each page request during warmup.	`5`

Cache proxy

The container includes a caching proxy that sits in front of the Next.js server.

Variable	Description	Default
`CACHE_MAX_ENTRIES`	Maximum number of pages to cache.	`1000`
`CACHE_MAX_ENTRY_SIZE`	Maximum size per cached entry in bytes.	`5242880` (5 MB)
`CACHE_DEFAULT_TTL`	Default cache time to live (TTL) in seconds.	`2592000` (30 days)
`CACHE_CDN_TTL`	Cache TTL in seconds for downstream CDN caches (e.g., CloudFront).	`3600` (1 hour)
`CACHE_DISABLED`	Set to `true` or `1` to disable caching entirely.	`false`
`CACHE_PROXY_DEBUG`	Set to `1` for verbose cache proxy logging.	`0`

The container includes a CORS proxy that allows the documentation frontend to make cross-origin requests (e.g., to your API for the API Explorer’s Try it feature). By default, only the docs domain itself is allowed. Use CORS_PROXY_ALLOWED_DOMAINS to allowlist additional domains.

Variable	Description	Default
`CORS_PROXY_ALLOWED_DOMAINS`	Comma-separated list of root domains to allow through the CORS proxy. Subdomains are matched automatically.	none

For example, to allow requests to api.plantstore.dev and auth.plantstore.dev:

1 ENV CORS_PROXY_ALLOWED_DOMAINS="plantstore.dev"

To allow multiple domains:

1 ENV CORS_PROXY_ALLOWED_DOMAINS="plantstore.dev,partner-api.example.com"

Debugging

Variable	Description	Default
`ENABLE_JAEGER`	Set to `true` to start Jaeger for distributed tracing. The Jaeger UI is available on port 16686.	`false`

Additional configuration

The following sections cover optional configurations for specific deployment scenarios.

Base path

By default, the self-hosted container serves documentation from root (/). Set NEXT_PUBLIC_BASE_PATH to serve from a sub-path instead, such as /docs. This is useful when your documentation shares a domain with other applications behind a reverse proxy.

The value must start with / and must not end with a trailing slash.

Build-time (recommended)

Runtime

Set NEXT_PUBLIC_BASE_PATH in your Dockerfile before running fern-generate. This patches the base path into the bundle at build time, so the container can run with a read-only filesystem.

1 FROM fernapi/fern-self-hosted:<latest-tag>
2 
3 COPY fern/ /fern/
4 
5 ENV NEXT_PUBLIC_BASE_PATH=/docs
6 
7 RUN fern-generate

With NEXT_PUBLIC_BASE_PATH=/docs, the documentation is accessible at http://localhost:3000/docs instead of http://localhost:3000/.

A single Docker image built without NEXT_PUBLIC_BASE_PATH can be configured at runtime to serve from any path. This lets you reuse one image across environments that may need different base paths.

Runtime generation

By default, fern-generate runs at Docker build time. Defer generation to runtime if you need to:

Pass configuration (environment variables, secrets) at runtime
Speed up Docker builds during development
Share a single image across multiple documentation configurations

Use the --only-deps flag to defer generation to runtime:

1 FROM fernapi/fern-self-hosted:<latest-tag>
2 
3 COPY fern/ /fern/
4 
5 RUN fern-generate --only-deps

This starts required services (PostgreSQL, MinIO, FDR) at build time but skips documentation generation. When the container starts, it automatically runs fern generate --docs.

Runtime generation requires network access at container startup. For air-gapped deployments, use the default build-time generation.

Air-gapped deployments with gRPC

If your API uses gRPC with dependencies from the Buf Schema Registry (BSR), the buf CLI fetches modules from buf.build during generation. This fails in air-gapped environments without network access.

Check for BSR dependencies

Check if your project has BSR dependencies in either location:

In buf.yaml:

1 version: v2
2 deps:
3   - buf.build/googleapis/googleapis
4   - buf.build/grpc-ecosystem/grpc-gateway

In generators.yml:

1 api:
2   specs:
3     - proto:
4         root: ./protos/
5         dependencies:
6           - buf.build/googleapis/googleapis

If there’s no deps or dependencies section (or only local paths), you can skip the rest of this section.

Choose a solution

Option 1: Build-time generation (recommended)

Run fern-generate at build time when network access is available:

1 FROM fernapi/fern-self-hosted:<latest-tag>
2 
3 COPY fern/ /fern/
4 
5 RUN fern-generate

This downloads BSR dependencies during the Docker build and bakes them into the image. No network access required at runtime.

Option 2: Vendor dependencies for runtime generation

Use this option when you don’t have all the information at build time and need the docs to generate differently at runtime, such as injecting environment variables at runtime.

To generate at runtime in an air-gapped environment, vendor buf dependencies locally:

1 FROM fernapi/fern-self-hosted:<latest-tag>
2 
3 # Install buf CLI for dependency caching
4 RUN npm install -g @bufbuild/buf
5 
6 # Copy fern configuration
7 COPY fern/ fern/
8 COPY protos/ protos/
9 
10 # Pre-fetch buf dependencies at build time (caches googleapis, protovalidate)
11 RUN cd protos && buf dep update
12 
13 # Build fern dependencies
14 RUN fern-generate --only-deps

Update buf.yaml to reference vendored dependencies:

1 # Before
2 deps:
3   - buf.build/googleapis/googleapis
4 
5 # After
6 deps:
7   - ./vendor/googleapis

See the Buf documentation on dependency management for more details.

Option 3: Specify dependencies in generators.yml

If you don’t have a buf.yaml file, you can specify proto dependencies directly in your generators.yml. The self-hosted container automatically creates a temporary buf.yaml from these dependencies during the build process.

generators.yml

1 api:
2   specs:
3     - proto:
4         root: ./protos/
5         dependencies:
6           - buf.build/googleapis/googleapis
7           - buf.build/bufbuild/protovalidate

This approach works with both build-time and runtime generation:

1 FROM fernapi/fern-self-hosted:<latest-tag>
2 
3 COPY fern/ /fern/
4 
5 # For build-time generation (recommended for air-gapped deployments)
6 RUN fern-generate
7 
8 # Or for runtime generation (requires network at startup)
9 # RUN fern-generate --only-deps

The container parses all generators.yml files in your fern directory, finds proto specs with dependencies but no buf.yaml, and creates the necessary configuration automatically.

Kubernetes deployment

Here is a sample Deployment and Service configuration. Replace your-registry/fern-docs:latest with your image name.

deployment.yaml:

deployment.yaml

1 apiVersion: apps/v1
2 kind: Deployment
3 metadata:
4   name: fern-docs
5   labels:
6     app: fern-docs
7 spec:
8   replicas: 1
9   selector:
10     matchLabels:
11       app: fern-docs
12   template:
13     metadata:
14       labels:
15         app: fern-docs
16     spec:
17       securityContext:
18         runAsNonRoot: true
19         runAsUser: 65532
20         runAsGroup: 65532
21         fsGroup: 65532
22         fsGroupChangePolicy: OnRootMismatch
23       containers:
24         - name: fern-docs
25           image: your-registry/fern-docs:latest
26           imagePullPolicy: IfNotPresent
27           ports:
28             - name: docs
29               containerPort: 3000
30               protocol: TCP
31             - name: health
32               containerPort: 8081
33               protocol: TCP
34           resources:
35             requests:
36               memory: "2Gi"
37               cpu: "1000m"
38             limits:
39               memory: "4Gi"
40               cpu: "2000m"
41           livenessProbe:
42             httpGet:
43               path: /liveness
44               port: 8081
45             initialDelaySeconds: 120
46             periodSeconds: 10
47             timeoutSeconds: 5
48             failureThreshold: 3
49           readinessProbe:
50             httpGet:
51               path: /readiness
52               port: 8081
53             initialDelaySeconds: 60
54             periodSeconds: 5
55             timeoutSeconds: 5
56             failureThreshold: 6
57           securityContext:
58             allowPrivilegeEscalation: false
59             runAsNonRoot: true
60             runAsUser: 65532
61             runAsGroup: 65532
62             privileged: false
63             readOnlyRootFilesystem: false
64             capabilities:
65               drop:
66                 - ALL
67       terminationGracePeriodSeconds: 30

service.yaml:

service.yaml

1 apiVersion: v1
2 kind: Service
3 metadata:
4   name: fern-docs
5   labels:
6     app: fern-docs
7 spec:
8   type: NodePort
9   ports:
10     - name: http
11       port: 80
12       targetPort: 3000
13       protocol: TCP
14       nodePort: 30080
15   selector:
16     app: fern-docs

For health check endpoint details, see Health check endpoints.