docs: add build-time generation, --only-deps flag, and gRPC air-gapped guidance (#2930)

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: Devin Logan <[email protected]>

Author: 3 people

fern/products/docs/pages/enterprise/self-hosted-set-up.mdx

@@ -12,6 +12,8 @@ Before setting up self-hosted documentation, ensure you have:
 - Access to your Fern project's `fern/` directory
 - A Docker Hub account (for accessing the private image)
 
+## Setup instructions
+
 <Steps>
 <Step title="Request Access to the Docker Image">
 
@@ -47,10 +49,16 @@ In the directory containing your `fern/` folder, create a new `Dockerfile` with
 FROM fernapi/fern-self-hosted:<latest-tag>
 
 COPY fern/ /fern/
+
+RUN fern-generate
 ```
 
 Replace `<latest-tag>` with the actual tag used in the previous step.
 
+<Info>
+  `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](#runtime-generation).
+  </Info>
+
 </Step>
 <Step title="Build Your Custom Docker Image">
 
@@ -93,5 +101,102 @@ instances:
 You can now deploy the image to your own infrastructure, allowing you to host the documentation on your own domain.
 
 </Step>
-</Steps>  
+</Steps>
+
+## 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:
+
+```dockerfile
+FROM fernapi/fern-self-hosted:<latest-tag>
+
+COPY fern/ /fern/
+
+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`.
+
+<Warning>
+Runtime generation requires network access at container startup. For air-gapped deployments, use the default build-time generation.
+</Warning>
+
+### Air-gapped deployments with gRPC
+
+If your API uses gRPC with dependencies from the [Buf Schema Registry](https://buf.build) (BSR), the `buf` CLI fetches modules from `buf.build` during generation. This fails in air-gapped environments without network access.
+
+<Steps>
+<Step title="Check for BSR dependencies">
+
+Look for a `deps` section in your `buf.yaml` file:
+
+```yaml
+version: v2
+deps:
+  - buf.build/googleapis/googleapis
+  - buf.build/grpc-ecosystem/grpc-gateway
+```
+
+If there's no `deps` section or only local paths, you can skip the rest of this section.
 
+</Step>
+<Step title="Choose a solution">
+
+<AccordionGroup>
+<Accordion title="Option 1: Build-time generation (recommended)" defaultOpen>
+
+Run `fern-generate` at build time when network access is available:
+
+```dockerfile
+FROM fernapi/fern-self-hosted:<latest-tag>
+
+COPY fern/ /fern/
+
+RUN fern-generate
+```
+
+This downloads BSR dependencies during the Docker build and bakes them into the image. No network access required at runtime.
+</Accordion>
+<Accordion title="Option 2: Vendor dependencies for runtime generation">
+
+To generate at runtime in an air-gapped environment, vendor buf dependencies locally:
+
+```dockerfile
+FROM fernapi/fern-self-hosted:<latest-tag>
+
+COPY fern/ /fern/
+
+RUN cd /fern && buf export . --output ./vendor
+
+RUN fern-generate --only-deps
+```
+
+Update `buf.yaml` to reference vendored dependencies:
+
+```yaml
+# Before
+deps:
+  - buf.build/googleapis/googleapis
+
+# After
+deps:
+  - ./vendor/googleapis
+```
+
+<Info>
+See the [Buf documentation on dependency management](https://buf.build/docs/bsr/module/dependency-management) for more details.
+</Info>
+</Accordion>
+</AccordionGroup>
+
+</Step>
+</Steps>