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:
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:
Create a Dockerfile
In the directory containing your fern/ folder, create a new Dockerfile with the following content:
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.
Run the Documentation
Start your self-hosted documentation:
The documentation will be available at localhost:<port-number>.
Additional configuration
The following sections cover optional configurations for specific deployment scenarios.
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:
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:
In generators.yml:
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:
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:
Update buf.yaml to reference vendored dependencies:
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.
This approach works with both build-time and runtime generation:
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.
