fix(docker): honor OMNIROUTE_BASE_PATH behind reverse-proxy subpaths (#8615)

* fix(docker): honor OMNIROUTE_BASE_PATH behind reverse-proxy subpaths

Next.js basePath is compile-time state; Docker now records the baked value,
forwards the env var as a build-arg, patches root-path images at container
start when needed, and probes health under the active subpath.

Hard Rule #13: scripts/docker/patch-basepath.sh and the entrypoint invoke Node
with a fixed argv; OMNIROUTE_BASE_PATH is read from process.env only — never
interpolated into sed/awk.

Closes #8600

* fix(docs): unblock CI for Docker basePath guide

Describe the build-time basePath marker as a sentinel file instead of a
fabricated env var, and replace the unsupported ```env fence with bash so
fumadocs/Shiki can compile DOCKER_GUIDE.md during DAST smoke.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(docker): add changelog fragment for #8615 basePath bundle patch

Co-authored-by: diegosouzapw <8016841+diegosouzapw@users.noreply.github.com>

---------

Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: diegosouzapw <8016841+diegosouzapw@users.noreply.github.com>

scripts/docker/ensure-docker-base-path.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+
+/**
+ * Compares OMNIROUTE_BASE_PATH at container start against BUILD_OMNIROUTE_BASE_PATH
+ * recorded during the image build. When they differ and the image was built for the
+ * domain root, rewrites the standalone bundle before Next.js starts.
+ *
+ * Hard Rule #13: the subpath is read only from process.env (or an injected env
+ * object in tests). Never accept it as a CLI argument or interpolate it into a
+ * shell sed/awk invocation — see scripts/docker/patch-basepath.sh.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { normalizeBasePath } from "../build/normalizeBasePath.mjs";
+import { patchStandaloneBasePath } from "./patch-standalone-base-path.mjs";
+
+const SENTINEL = "BUILD_OMNIROUTE_BASE_PATH";
+
+function readBakedBasePath(appRoot) {
+  const sentinelPath = path.join(appRoot, SENTINEL);
+  if (!fs.existsSync(sentinelPath)) return "";
+  return normalizeBasePath(fs.readFileSync(sentinelPath, "utf8"));
+}
+
+function writeBakedBasePath(appRoot, basePath) {
+  fs.writeFileSync(path.join(appRoot, SENTINEL), `${basePath}\n`);
+}
+
+/**
+ * @param {object} [opts]
+ * @param {string} [opts.appRoot]
+ * @param {NodeJS.ProcessEnv} [opts.env]
+ */
+export function ensureDockerBasePath(opts = {}) {
+  const appRoot = opts.appRoot || process.cwd();
+  const runtime = normalizeBasePath(opts.env?.OMNIROUTE_BASE_PATH ?? process.env.OMNIROUTE_BASE_PATH);
+  const baked = readBakedBasePath(appRoot);
+
+  if (runtime === baked) {
+    return { action: "noop", runtime, baked };
+  }
+
+  if (!runtime && baked) {
+    throw new Error(
+      `This OmniRoute image was built for subpath ${baked}, but OMNIROUTE_BASE_PATH is unset. ` +
+        `Set OMNIROUTE_BASE_PATH=${baked} or rebuild without the build-arg.`
+    );
+  }
+
+  const patchResult = patchStandaloneBasePath({
+    appRoot,
+    fromBasePath: baked,
+    toBasePath: runtime,
+  });
+  writeBakedBasePath(appRoot, runtime);
+  return { action: "patched", runtime, baked, patchResult };
+}
+
+function main() {
+  try {
+    const result = ensureDockerBasePath();
+    if (result.action === "patched") {
+      const { patchResult, runtime } = result;
+      console.log(
+        `[ensure-docker-base-path] Applied runtime subpath ${runtime} ` +
+          `(manifests=${patchResult.patchedManifests}, textFiles=${patchResult.patchedTextFiles})`
+      );
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`[ensure-docker-base-path] ${message}`);
+    console.error(
+      "[ensure-docker-base-path] Rebuild the image with the same subpath, e.g.\n" +
+        "  docker compose build --build-arg OMNIROUTE_BASE_PATH=/omniroute"
+    );
+    process.exit(1);
+  }
+}
+
+const isEntrypoint =
+  Boolean(process.argv[1]) && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isEntrypoint) {
+  main();
+}

scripts/docker/patch-basepath.sh

@@ -0,0 +1,8 @@
+#!/bin/sh
+# Hard Rule #13 — OMNIROUTE_BASE_PATH must travel via the process environment.
+# This wrapper never expands the subpath into sed/awk/shell script text; Node
+# reads OMNIROUTE_BASE_PATH from env inside ensure-docker-base-path.mjs.
+set -eu
+
+SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+exec node "${SCRIPT_DIR}/ensure-docker-base-path.mjs"

scripts/docker/patch-standalone-base-path.mjs

@@ -0,0 +1,168 @@
+/**
+ * Rewrites Next.js standalone manifests and embedded basePath literals so a bundle
+ * built for the domain root can serve under OMNIROUTE_BASE_PATH at container start.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { normalizeBasePath } from "../build/normalizeBasePath.mjs";
+
+const JSON_MANIFEST_NAMES = new Set([
+  "routes-manifest.json",
+  "prerender-manifest.json",
+  "required-server-files.json",
+  "images-manifest.json",
+  "app-path-routes-manifest.json",
+]);
+
+/**
+ * @param {string} appRoot
+ * @returns {string[]}
+ */
+export function discoverNextDistRoots(appRoot) {
+  const candidates = [".build/next", ".next", path.join(".build", "next")];
+  const found = [];
+  for (const rel of candidates) {
+    const abs = path.join(appRoot, rel);
+    if (fs.existsSync(path.join(abs, "routes-manifest.json"))) {
+      found.push(abs);
+    }
+  }
+  return found;
+}
+
+/**
+ * @param {unknown} node
+ * @param {string} basePath
+ */
+function patchJsonNode(node, basePath) {
+  if (!node || typeof node !== "object") return;
+  if (Array.isArray(node)) {
+    for (const entry of node) patchJsonNode(entry, basePath);
+    return;
+  }
+  for (const [key, value] of Object.entries(node)) {
+    if (key === "basePath" && typeof value === "string") {
+      node[key] = basePath;
+      continue;
+    }
+    patchJsonNode(value, basePath);
+  }
+}
+
+/**
+ * @param {string} filePath
+ * @param {string} basePath
+ */
+export function patchJsonManifestFile(filePath, basePath) {
+  const raw = fs.readFileSync(filePath, "utf8");
+  const parsed = JSON.parse(raw);
+  patchJsonNode(parsed, basePath);
+  const next = `${JSON.stringify(parsed, null, 2)}\n`;
+  if (next !== raw) {
+    fs.writeFileSync(filePath, next);
+    return true;
+  }
+  return false;
+}
+
+const BASE_PATH_LITERAL_RE =
+  /basePath\s*:\s*(?:""|''|`{2})|basePath\s*:\s*void 0|"basePath"\s*:\s*""/g;
+
+/**
+ * @param {string} content
+ * @param {string} basePath
+ */
+export function patchBasePathLiterals(content, basePath) {
+  const escaped = basePath.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+  return content.replace(BASE_PATH_LITERAL_RE, (match) => {
+    if (match.startsWith('"basePath"')) return `"basePath":"${escaped}"`;
+    if (match.includes("void 0")) return `basePath:"${escaped}"`;
+    return `basePath:"${escaped}"`;
+  });
+}
+
+/**
+ * @param {string} rootDir
+ * @param {string} basePath
+ */
+function walkAndPatchTextFiles(rootDir, basePath) {
+  let patchedFiles = 0;
+  const stack = [rootDir];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    if (!current) continue;
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(full);
+        continue;
+      }
+      if (!/\.(?:js|json|cjs|mjs)$/.test(entry.name)) continue;
+      const before = fs.readFileSync(full, "utf8");
+      const after = patchBasePathLiterals(before, basePath);
+      if (after !== before) {
+        fs.writeFileSync(full, after);
+        patchedFiles += 1;
+      }
+    }
+  }
+  return patchedFiles;
+}
+
+/**
+ * @param {object} opts
+ * @param {string} opts.appRoot standalone bundle root (cwd in Docker)
+ * @param {string} opts.fromBasePath normalized baked base path
+ * @param {string} opts.toBasePath normalized runtime base path
+ */
+export function patchStandaloneBasePath({ appRoot, fromBasePath, toBasePath }) {
+  const from = normalizeBasePath(fromBasePath);
+  const to = normalizeBasePath(toBasePath);
+  if (from === to) {
+    return { changed: false, patchedManifests: 0, patchedTextFiles: 0, distRoots: [] };
+  }
+  if (from) {
+    throw new Error(
+      `runtime OMNIROUTE_BASE_PATH (${to || "(root)"}) does not match the image build ` +
+        `(${from}). Rebuild with --build-arg OMNIROUTE_BASE_PATH=${to || '""'}.`
+    );
+  }
+  if (!to) {
+    throw new Error("patchStandaloneBasePath requires a non-empty target base path");
+  }
+
+  const distRoots = discoverNextDistRoots(appRoot);
+  if (distRoots.length === 0) {
+    throw new Error(
+      "could not locate routes-manifest.json under .build/next or .next in the standalone bundle"
+    );
+  }
+
+  let patchedManifests = 0;
+  let patchedTextFiles = 0;
+  for (const distRoot of distRoots) {
+    for (const name of JSON_MANIFEST_NAMES) {
+      const manifestPath = path.join(distRoot, name);
+      if (!fs.existsSync(manifestPath)) continue;
+      if (patchJsonManifestFile(manifestPath, to)) patchedManifests += 1;
+    }
+    const serverDir = path.join(distRoot, "server");
+    if (fs.existsSync(serverDir)) patchedTextFiles += walkAndPatchTextFiles(serverDir, to);
+    const staticDir = path.join(distRoot, "static");
+    if (fs.existsSync(staticDir)) patchedTextFiles += walkAndPatchTextFiles(staticDir, to);
+  }
+
+  for (const entry of ["server.js", "server-ws.mjs"]) {
+    const serverEntry = path.join(appRoot, entry);
+    if (!fs.existsSync(serverEntry)) continue;
+    const before = fs.readFileSync(serverEntry, "utf8");
+    const after = patchBasePathLiterals(before, to);
+    if (after !== before) {
+      fs.writeFileSync(serverEntry, after);
+      patchedTextFiles += 1;
+    }
+  }
+
+  return { changed: true, patchedManifests, patchedTextFiles, distRoots, toBasePath: to };
+}