Add air-gapped docs container (#2978)

* Add air-gapped docs container build

Adds two new build commands and a distroless nginx container for serving
documentation offline without network access.

Made-with: Cursor

* Update build/Targets.fs

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

* Add dedicated air-gapped publish environment

- Add `air-gapped` environment to assembler.yml with no GTM/Optimizely,
  allow_indexing: false, and AIR_GAPPED feature flag
- Add AirGappedEnabled feature flag to FeatureFlags.cs
- Add AirGapped flag to FrontendConfig (disables telemetry, signals frontend)
- Assembler header conditionally renders elastic-docs-header instead of
  elastic-nav.js for air-gapped, avoiding all external CDN dependencies
- Load isolated.ts (registers <elastic-docs-header> web component) when
  airGapped is true; override --offset-top via body.air-gapped CSS class
- Skip API health checks in NavigationSearch, FullPageSearch, and
  useSearchAvailability for air-gapped builds
- Hide DeploymentInfo section in header via explicit air-gapped prop
- Switch Air_Gapped_Build target to use --environment air-gapped

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: 3 people

build/CommandLine.fs

@@ -54,6 +54,9 @@ type Build =
     | [<CliPrefix(CliPrefix.None);Hidden;SubCommand>] PublishContainers
     | [<CliPrefix(CliPrefix.None);Hidden;SubCommand>] PublishZip
 
+    | [<CliPrefix(CliPrefix.None);SubCommand>] Air_Gapped_Build
+    | [<CliPrefix(CliPrefix.None);SubCommand>] Air_Gapped_Run
+
     | [<CliPrefix(CliPrefix.None);SubCommand>] Release
 
     | [<Inherit;AltCommandLine("-s")>] Single_Target
@@ -73,6 +76,9 @@ with
             | Integrate -> "alias to providing: test --test-suite=integration"
             | Test -> "runs a clean build and then runs all the tests unless --test-suite is provided"
 
+            | Air_Gapped_Build -> "Clones, builds docs with html exporter, and packages into an air-gapped Docker container"
+            | Air_Gapped_Run -> "Runs the air-gapped docs container on port 8080"
+
             | Release -> "runs build, tests, and create and validates the packages shy of publishing them"
             | Publish -> "Publishes artifacts"
             | Format _ -> "runs dotnet format"

build/Targets.fs

@@ -4,6 +4,8 @@
 
 module Targets
 
+open System.IO
+open System.IO.Compression
 open Argu
 open CommandLine
 open Fake.Core
@@ -150,6 +152,73 @@ let private runTests (testSuite: TestSuite) _ =
         )
     }
 
+let private compressibleExtensions = set [".html"; ".css"; ".js"; ".json"; ".svg"; ".xml"; ".txt"]
+
+let private gzipCompressDirectory (directory: string) =
+    // Remove stale .gz files from any previous run to avoid orphaned pairs
+    Directory.EnumerateFiles(directory, "*.gz", SearchOption.AllDirectories)
+    |> Seq.toArray
+    |> Array.iter File.Delete
+
+    let files =
+        Directory.EnumerateFiles(directory, "*", SearchOption.AllDirectories)
+        |> Seq.filter (fun f ->
+            match Path.GetExtension(f) with
+            | null -> false
+            | ext -> compressibleExtensions.Contains(ext.ToLowerInvariant())
+        )
+        |> Seq.toArray
+
+    printfn $"Compressing %d{files.Length} files in %s{directory}"
+
+    files
+    |> Array.Parallel.iter (fun file ->
+        let gzPath = file + ".gz"
+        use input = File.OpenRead(file)
+        use output = File.Create(gzPath)
+        use gzip = new GZipStream(output, CompressionLevel.SmallestSize)
+        input.CopyTo(gzip)
+    )
+
+    // Replace originals with zero-byte placeholders so nginx try_files can resolve
+    // paths, while gzip_static always serves the .gz version
+    for file in files do
+        File.Delete(file)
+        File.Create(file).Dispose()
+
+    printfn "Compression complete"
+
+let private airGappedBuild _ =
+    let assemblyDir = Path.Combine(Paths.Root.FullName, ".artifacts", "assembly")
+    if Directory.Exists(assemblyDir) then
+        Directory.Delete(assemblyDir, true)
+
+    exec { run "dotnet" "run" "--project" "src/tooling/docs-builder" "--" "assembler" "clone" "--environment" "air-gapped" }
+    exec { run "dotnet" "run" "--project" "src/tooling/docs-builder" "--" "assembler" "build" "--exporters" "html" "--environment" "air-gapped" }
+    let searchDir = Path.Combine(assemblyDir, "docs", "_search")
+    if Directory.Exists(searchDir) then
+        Directory.Delete(searchDir, true)
+
+    File.WriteAllText(
+        Path.Combine(assemblyDir, "index.html"),
+        """<meta http-equiv="refresh" content="0;url=/docs">"""
+    )
+
+    gzipCompressDirectory assemblyDir
+
+    exec {
+        run "docker" "build"
+            "-f" "build/air-gapped/Dockerfile"
+            "--build-context" "content=.artifacts/assembly"
+            "--build-context" "config=build/air-gapped"
+            "-t" "elastic-docs-air-gapped"
+            "build/air-gapped"
+    }
+
+let private airGappedRun _ =
+    printfn "Running at http://localhost:8080"
+    exec { run "docker" "run" "-p" "127.0.0.1:8080:8080" "elastic-docs-air-gapped" }
+
 let private validateLicenses _ =
     let args = ["-u"; "-t"; "-i"; "docs-builder.sln"; "--use-project-assets-json"
                 "--forbidden-license-types"; "build/forbidden-license-types.json"
@@ -196,6 +265,8 @@ let Setup (parsed:ParseResults<Build>) =
         | RunLocalContainer -> Build.Step runLocalContainer
         | PublishZip -> Build.Step publishZip
         | ValidateLicenses -> Build.Step validateLicenses
+        | Air_Gapped_Build -> Build.Cmd [] [] airGappedBuild
+        | Air_Gapped_Run -> Build.Cmd [] [] airGappedRun
 
         // flags
         | Single_Target

build/air-gapped/Dockerfile

@@ -0,0 +1,6 @@
+# syntax=docker/dockerfile:1
+
+FROM cgr.dev/chainguard/nginx:latest
+COPY --from=config nginx.conf /etc/nginx/nginx.conf
+COPY --from=content . /usr/share/nginx/html/
+EXPOSE 8080

build/air-gapped/nginx.conf

@@ -0,0 +1,39 @@
+worker_processes auto;
+error_log /dev/stderr warn;
+pid /tmp/nginx.pid;
+
+events {
+    worker_connections 1024;
+}
+
+http {
+    include /etc/nginx/mime.types;
+    default_type application/octet-stream;
+
+    access_log /dev/stdout combined;
+
+    sendfile on;
+    tcp_nopush on;
+    keepalive_timeout 65;
+
+    gzip_static always;
+    gunzip on;
+
+    server {
+        listen 8080;
+        server_name _;
+        root /usr/share/nginx/html;
+
+        add_header X-Content-Type-Options "nosniff" always;
+        add_header X-Frame-Options "SAMEORIGIN" always;
+        add_header Referrer-Policy "strict-origin-when-cross-origin" always;
+
+        index index.html;
+
+        location / {
+            try_files $uri $uri/index.html =404;
+        }
+
+        error_page 404 /404.html;
+    }
+}

config/assembler.yml

@@ -46,6 +46,13 @@ environments:
       enabled: false
     feature_flags:
       SEARCH_OR_ASK_AI: true
+  air-gapped:
+    uri: http://localhost:8080
+    path_prefix: docs
+    content_source: current
+    allow_indexing: false
+    feature_flags:
+      AIR_GAPPED: true
 
 shared_configuration:
   stack: &stack

src/Elastic.Documentation.Configuration/Builder/FeatureFlags.cs

@@ -38,6 +38,12 @@ public bool StagingElasticNavEnabled
 		set => _featureFlags["staging-elastic-nav"] = value;
 	}
 
+	public bool AirGappedEnabled
+	{
+		get => IsEnabled("air-gapped");
+		set => _featureFlags["air-gapped"] = value;
+	}
+
 	public bool DiagnosticsPanelEnabled
 	{
 		get => IsEnabled("diagnostics-panel");

src/Elastic.Documentation.Site/Assets/assembler.css

@@ -28,6 +28,15 @@
 	min-height: var(--offset-top);
 }
 
+/* Air-gapped: uses elastic-docs-header web component instead of elastic nav */
+body.air-gapped {
+	--offset-top: 48px;
+}
+
+body.air-gapped elastic-docs-header .euiHeader {
+	padding-inline: calc((100vw - var(--max-layout-width)) / 2 + 8px);
+}
+
 #elastic-nav {
 	@media screen and (min-width: 1200px) {
 		[data-component='Container'] {

src/Elastic.Documentation.Site/Assets/config.ts

@@ -10,6 +10,7 @@ export interface DocsConfig {
     telemetryEnabled: boolean
     rootPath: string // '/docs' for assembler, '' for codex and isolated
     apiBasePath: string // '/docs/_api' for assembler, '/api' for codex
+    airGapped: boolean
 }
 
 declare global {
@@ -24,6 +25,7 @@ const DEFAULT_CONFIG: DocsConfig = {
     telemetryEnabled: false,
     rootPath: '',
     apiBasePath: '/docs/_api',
+    airGapped: false,
 }
 
 export const config: DocsConfig = window.__DOCS_CONFIG__ ?? DEFAULT_CONFIG

src/Elastic.Documentation.Site/Assets/main.ts

@@ -41,7 +41,7 @@ import('./web-components/AppliesToPopover')
 import('./web-components/FullPageSearch/FullPageSearchComponent')
 import('./web-components/Diagnostics/DiagnosticsComponent')
 
-if (config.buildType === 'isolated') {
+if (config.buildType === 'isolated' || config.airGapped) {
     import('./isolated')
 } else if (config.buildType === 'codex') {
     import('./codex')

src/Elastic.Documentation.Site/Assets/web-components/FullPageSearch/FullPageSearchComponent.tsx

@@ -23,9 +23,10 @@ const FullPageSearchInner = () => {
         },
         staleTime: 60 * 60 * 1000, // 60 minutes
         retry: false,
+        enabled: !config.airGapped,
     })
 
-    if (!isApiAvailable) {
+    if (config.airGapped || !isApiAvailable) {
         return null
     }