Skip to content

build: replace nginx runtime with a pinned node static server - #46

Merged
vigneshrajsb merged 3 commits into
mainfrom
replace-nginx-with-node-runtime
Nov 18, 2026
Merged

vigneshrajsb merged 3 commits into
mainfrom
replace-nginx-with-node-runtime

Conversation

@vigneshrajsb

@vigneshrajsb vigneshrajsb commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Reader and task

  • Audience: maintainers and operators who build and deploy the docs image.
  • Task/outcome: the image no longer uses nginx. A pinned Node runtime serves the static export with the same routing rules.

Source of truth

  • Exact owning repository revisions, PR head SHAs, or immutable artifacts: oven/bun:1.4.4-alpine and node:24.22.3-alpine3.24, both pinned by digest.
  • Frontmatter verification baseline added or reused: N/A, no page changes.
  • Product or runtime verification: built the image and checked /, a raw .md route, a missing .md, /docs/cm*, an unknown route, a missing asset, the non-root user, and a clean SIGTERM exit.
  • Contract checks (schema / OpenAPI / CLI; identify any SKIP): N/A, no schema, API, or CLI claims changed.
  • Unavailable or unresolved sources: none.

Documentation changes

  • Changed pages: none.
  • ASD-STE100 human review: N/A, no prose changed.
  • Navigation or redirects: none. server.mjs keeps the nginx behavior: .html before a same-name directory, SPA fallback to index.html, 404.html for misses, and 404 for the retired /docs/cm routes.
  • Raw Markdown projection: unchanged output. .md is served as text/markdown; charset=utf-8 and a missing file returns 404. The regex check on default.conf is replaced by tests/server.test.ts, which tests the same contracts against the running server.
  • External state: sanitized authorization and cleanup assertion, with only
    public or non-sensitive references (keep private identifiers in task scratch): N/A, no external state.
  • Screenshots, catalog status, and manual pixel/state review: N/A.

Other changes:

  • The container listens on 8080 as the node user, so containerPort and probes move to 8080. The service port stays 80.
  • The runtime runs apk upgrade and removes npm, npx, corepack, and yarn. A Grype scan shows no fixable CVEs. The remaining findings are OpenSSL 3.5.9 and busybox advisories with no fixed release yet.
  • CI and the deploy workflow move to Bun 1.4.4 to match the image. bun install --frozen-lockfile passes with the current lockfile.
  • A new image CI job builds the Dockerfile, runs scripts/smokeImage.sh against the container (routing contract, non-root user, clean SIGTERM exit), and fails on High/Critical CVEs that have a fixed release.
  • The server normalizes paths before routing, so /docs//cm and encoded .. cannot bypass the retired-route 404 or leave the root. It also sends ETag and Last-Modified and answers revalidation with 304, as nginx did.

Verification

  • Formatted changed files
  • Kept source-review evidence and non-actionable implementation details out of end-user prose
  • Confirmed that each changed sentence helps the reader understand, complete, verify, or recover the task
  • Reviewed all 53 rule rows in .agents/skills/update-lifecycle-docs/references/ste100-review.md
  • bun run check:styles
  • Updated the style baseline only after the complete human review
  • bun run check:raw
  • bun run verify
  • bun run check:contracts --require-all when schema, API, or CLI claims changed
  • Checked changed routes with an approved desktop browser inspection tool
  • Checked every theme enabled by the current theme config
  • Ran bun run check:screenshots when visuals changed
  • Confirmed screenshots contain no secrets or personal/private data
  • Confirmed tracked guidance has no contributor-specific paths, hosts, credentials, or fixture identities

Serve the static export from node:24.22.3-alpine3.24 with a dependency-free server that keeps the raw Markdown, retired route, and 404 contracts. Pin oven/bun 1.4.4 for the builder and CI.
Normalize request paths before routing, never look outside the root for /, add ETag/Last-Modified revalidation, and bound shutdown. CI now builds the image, runs scripts/smokeImage.sh, and fails on fixable High/Critical CVEs.
@vigneshrajsb
vigneshrajsb marked this pull request as ready for review November 18, 2026 20:36
@vigneshrajsb
vigneshrajsb requested a review from a team as a code owner November 18, 2026 20:36
@vigneshrajsb
vigneshrajsb merged commit 1660c18 into main Nov 18, 2026
2 checks passed
@vigneshrajsb
vigneshrajsb deleted the replace-nginx-with-node-runtime branch November 18, 2026 20:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants