Set up self-hosted documentation

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 organization access token (OAT) from Fern (for pulling the private image)

Setup instructions

$
docker login --username fernenterprise

$
echo "$DOCKERHUB_OAT" | docker login --username fernenterprise --password-stdin

$
docker pull fernenterprise/fern-self-hosted:latest

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

your-project/
├── Dockerfile
└── fern/
    ├── fern.config.json
    ├── docs.yml
    └── ...

1
FROM fernenterprise/fern-self-hosted:latest
2
3
COPY fern/ /fern/
4
5
RUN fern-generate

$
docker build -t self-hosted-docs .

$
docker run -p 3000:3000 self-hosted-docs

Custom domain

Your documentation uses 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

To override the domain at runtime (for example, when the actual hostname differs from the custom-domain in docs.yml), set the CUSTOM_DOMAIN environment variable:

$
docker run -p 3000:3000 -e CUSTOM_DOMAIN=docs.plantstore.dev self-hosted-docs

See Environment variables for details.

Environment variables

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

General

Cache warmup

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

Cache proxy

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

Cross-origin resource sharing (CORS) proxy

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.

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

On-page feedback

In self-hosted mode, on-page feedback events are emitted as structured JSON logs to the container’s stdout, prefixed with [fern-docs-feedback]. You can filter for these in your logging infrastructure:

$
docker logs <container-id> 2>&1 | grep "\[fern-docs-feedback\]"

Each log line contains an event name, a timestamp, and a set of properties:

1
[fern-docs-feedback] {"event":"feedback_submitted","timestamp":"2026-01-15T12:34:56.789Z","properties":{"satisfied":true,"message":"Great docs!","email":"user@example.com","type":"on-page-feedback"}}

Tracked events

Properties

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.

1
FROM fernenterprise/fern-self-hosted:latest
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/.

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 fernenterprise/fern-self-hosted:latest
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.

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.

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

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

1
FROM fernenterprise/fern-self-hosted:latest
2
3
COPY fern/ /fern/
4
5
RUN fern-generate

1
FROM fernenterprise/fern-self-hosted:latest
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

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

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

1
FROM fernenterprise/fern-self-hosted:latest
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

Kubernetes deployment

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

Apply the configuration:

$
kubectl apply -f deployment.yaml
$
kubectl apply -f service.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:

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.