From f7c27b681a7a74f8d92c16bad9a544f7f4df5c58 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Mon, 13 Jul 2026 18:48:12 +0000 Subject: [PATCH 1/3] docs: prefer docs.yml subpath for self-hosted base path Co-Authored-By: ryanstep --- .../pages/self-hosted/self-hosted-set-up.mdx | 28 +++++++++++-------- 1 file changed, 17 insertions(+), 11 deletions(-) diff --git a/fern/products/docs/pages/self-hosted/self-hosted-set-up.mdx b/fern/products/docs/pages/self-hosted/self-hosted-set-up.mdx index 965a50168..1c2f01780 100644 --- a/fern/products/docs/pages/self-hosted/self-hosted-set-up.mdx +++ b/fern/products/docs/pages/self-hosted/self-hosted-set-up.mdx @@ -142,7 +142,7 @@ Configure the self-hosted container's behavior by setting environment variables | `CUSTOM_DOMAIN` | Override the `custom-domain` from `docs.yml` at runtime. Useful when the hostname where the docs are actually served differs from the domain in `docs.yml`. Accepts a bare hostname (e.g., `docs.plantstore.dev`); any `https://` or `http://` prefix is stripped automatically. | Value from `docs.yml` `custom-domain` | | `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](#base-path) for details. | none (serves from `/`) | +| `NEXT_PUBLIC_BASE_PATH` | Override the base path inferred from your `docs.yml` sub-path, or serve from a sub-path without configuring `docs.yml`. The value must start with `/` and have no trailing slash (e.g., `/docs`). See [Base path](#base-path) for details. | Inferred from `docs.yml` sub-path (else serves from `/`) | ### Cache warmup @@ -230,9 +230,21 @@ The following sections cover optional configurations for specific deployment sce ### 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. +By default, the self-hosted container serves documentation from root (`/`). To serve from a sub-path instead, such as `/docs`, add the sub-path to your `docs.yml` instance. Fern infers the base path from the sub-path, so no environment variable is required. -The value must start with `/` and must not end with a trailing slash. +Apply the sub-path to both the instance `url` and its `custom-domain`: + +```yaml docs.yml +instances: + - url: plantstore.docs.buildwithfern.com/docs + custom-domain: docs.plantstore.dev/docs +``` + +`fern generate --docs` validates that an instance's `url` and `custom-domain` share the same base path, so the sub-path must be on both or neither. With this configuration, the documentation is accessible at `http://localhost:3000/docs` instead of `http://localhost:3000/`. + +#### Override the base path with an environment variable + +Set `NEXT_PUBLIC_BASE_PATH` to override the sub-path inferred from `docs.yml`. The environment variable takes precedence, so use it to serve from a different path than `docs.yml` defines, or to set a base path without editing `docs.yml`. The value must start with `/` and must not end with a trailing slash. @@ -258,18 +270,12 @@ Pass `NEXT_PUBLIC_BASE_PATH` when starting the container. The base path is patch docker run -p 3000:3000 -e NEXT_PUBLIC_BASE_PATH=/docs self-hosted-docs ``` - -Runtime patching modifies files inside the container on startup, so it is not compatible with `readOnlyRootFilesystem: true` in Kubernetes. Use build-time patching if your security context requires a read-only root filesystem. - +Runtime patching modifies files inside the container on startup, so it's not compatible with `readOnlyRootFilesystem: true` in Kubernetes. Use build-time patching if your security context requires a read-only root filesystem. -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. - +A single Docker image built without a base path can be patched at runtime to serve from any path, letting you reuse one image across environments that need different base paths. ### Runtime generation From 5fb63525e70c7e920ca3a92c743eb69cc3900119 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Mon, 13 Jul 2026 18:56:35 +0000 Subject: [PATCH 2/3] docs: clarify docs.yml subpath is the recommended base path approach Co-Authored-By: ryanstep --- fern/products/docs/pages/self-hosted/self-hosted-set-up.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/products/docs/pages/self-hosted/self-hosted-set-up.mdx b/fern/products/docs/pages/self-hosted/self-hosted-set-up.mdx index 1c2f01780..1e025d736 100644 --- a/fern/products/docs/pages/self-hosted/self-hosted-set-up.mdx +++ b/fern/products/docs/pages/self-hosted/self-hosted-set-up.mdx @@ -230,7 +230,7 @@ The following sections cover optional configurations for specific deployment sce ### Base path -By default, the self-hosted container serves documentation from root (`/`). To serve from a sub-path instead, such as `/docs`, add the sub-path to your `docs.yml` instance. Fern infers the base path from the sub-path, so no environment variable is required. +By default, the self-hosted container serves documentation from root (`/`). To serve from a sub-path instead, such as `/docs`, add the sub-path to your `docs.yml` instance. Fern infers the base path from that sub-path, so setting `NEXT_PUBLIC_BASE_PATH` in your Dockerfile is no longer required. This is the recommended approach. Apply the sub-path to both the instance `url` and its `custom-domain`: From 0b6180ef4925f87da6364597bfa57806ff25fb02 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Tue, 14 Jul 2026 13:04:39 +0000 Subject: [PATCH 3/3] docs: frame env var base path as override for cross-environment image reuse Co-Authored-By: ryanstep --- fern/products/docs/pages/self-hosted/self-hosted-set-up.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/fern/products/docs/pages/self-hosted/self-hosted-set-up.mdx b/fern/products/docs/pages/self-hosted/self-hosted-set-up.mdx index 1e025d736..b85517b5c 100644 --- a/fern/products/docs/pages/self-hosted/self-hosted-set-up.mdx +++ b/fern/products/docs/pages/self-hosted/self-hosted-set-up.mdx @@ -230,7 +230,7 @@ The following sections cover optional configurations for specific deployment sce ### Base path -By default, the self-hosted container serves documentation from root (`/`). To serve from a sub-path instead, such as `/docs`, add the sub-path to your `docs.yml` instance. Fern infers the base path from that sub-path, so setting `NEXT_PUBLIC_BASE_PATH` in your Dockerfile is no longer required. This is the recommended approach. +By default, the self-hosted container serves documentation from root (`/`). To serve from a sub-path instead, such as `/docs`, add the sub-path to your `docs.yml` instance. Fern infers the base path from that sub-path, with no environment variable required. This is the preferred approach. Apply the sub-path to both the instance `url` and its `custom-domain`: @@ -244,7 +244,7 @@ instances: #### Override the base path with an environment variable -Set `NEXT_PUBLIC_BASE_PATH` to override the sub-path inferred from `docs.yml`. The environment variable takes precedence, so use it to serve from a different path than `docs.yml` defines, or to set a base path without editing `docs.yml`. The value must start with `/` and must not end with a trailing slash. +Set `NEXT_PUBLIC_BASE_PATH` when you need a base path that differs from the `docs.yml` sub-path, such as reusing one prebuilt image across environments that serve from different paths. The environment variable overrides the sub-path inferred from `docs.yml`. The value must start with `/` and must not end with a trailing slash.