From 17513ec5b03c39b77317581098491441182e2a62 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mois=C3=A9s?= <118999648+EstoesMoises@users.noreply.github.com> Date: Thu, 12 Nov 2026 14:00:12 +0000 Subject: [PATCH] Add production container image, health endpoint and CI - Dockerfile: multi-stage Next.js standalone build on Node 24, non-root uid 10001, works with a read-only root filesystem - GET /api/healthz for container liveness/readiness probes - next.config.mjs: output standalone - GitHub Actions CI: lint, unit tests, build, and a hardened container smoke test - README: container usage Co-Authored-By: Claude Opus 5.5 --- .dockerignore | 24 ++++++++++++++ .github/workflows/ci.yml | 55 +++++++++++++++++++++++++++++++++ Dockerfile | 54 ++++++++++++++++++++++++++++++++ README.md | 16 ++++++++++ next.config.mjs | 6 +++- src/app/api/healthz/route.ts | 10 ++++++ src/server/healthzRoute.test.ts | 16 ++++++++++ 7 files changed, 180 insertions(+), 1 deletion(-) create mode 100644 .dockerignore create mode 100644 .github/workflows/ci.yml create mode 100644 Dockerfile create mode 100644 src/app/api/healthz/route.ts create mode 100644 src/server/healthzRoute.test.ts diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..f52609d --- /dev/null +++ b/.dockerignore @@ -0,0 +1,24 @@ +.git +.github +.next +node_modules +.pnpm-store +dist +coverage +test-results +playwright-report +*.tsbuildinfo +**/.env* +.DS_Store + +# Agent tooling and design docs are not part of the runtime image. +.agents +.claude +.codex +.impeccable +.superpowers +.worktrees +docs +e2e +Dockerfile +.dockerignore diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..9f243aa --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,55 @@ +name: CI + +on: + pull_request: + push: + branches: [main] + +permissions: + contents: read + +concurrency: + group: ci-${{ github.ref }} + cancel-in-progress: true + +jobs: + test: + name: Lint, test and build + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: pnpm/action-setup@v4 + - uses: actions/setup-node@v4 + with: + node-version: 24 + cache: pnpm + - run: pnpm install --frozen-lockfile + - run: pnpm lint + - run: pnpm test + - run: pnpm build + + container: + name: Container image + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: docker/setup-buildx-action@v3 + - name: Build image + uses: docker/build-push-action@v6 + with: + context: . + load: true + tags: stack-api-utilities:ci + - name: Smoke-test hardened container + run: | + set -euo pipefail + docker run -d --name smoke -p 3000:3000 \ + --read-only --tmpfs /tmp --tmpfs /app/.next/cache:uid=10001,gid=10001 \ + --cap-drop ALL --security-opt no-new-privileges \ + stack-api-utilities:ci + for _ in $(seq 1 30); do + curl -sf http://127.0.0.1:3000/api/healthz && exit 0 + sleep 1 + done + docker logs smoke + exit 1 diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..9d8fcd4 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,54 @@ +# syntax=docker/dockerfile:1.7 +# +# Production image for Stack API Utilities (Next.js standalone server). +# +# docker build -t stack-api-utilities . +# docker run --rm -p 3000:3000 \ +# -e STACK_API_UTILITIES_PUBLIC_ORIGIN=http://localhost:3000 stack-api-utilities +# +# The server is stateless: customer credentials and datasets stay in the +# browser, and OAuth PKCE state travels in a short-lived cookie. The image +# therefore needs no secrets and no persistent volume. + +ARG NODE_VERSION=24 + +FROM node:${NODE_VERSION}-bookworm-slim AS base +ENV PNPM_HOME=/pnpm \ + PATH=/pnpm:$PATH \ + NEXT_TELEMETRY_DISABLED=1 +RUN corepack enable +WORKDIR /app + +FROM base AS deps +COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./ +RUN --mount=type=cache,id=pnpm-store,target=/pnpm/store \ + pnpm config set store-dir /pnpm/store && \ + pnpm install --frozen-lockfile + +FROM base AS build +COPY --from=deps /app/node_modules ./node_modules +COPY . . +RUN pnpm build + +FROM node:${NODE_VERSION}-bookworm-slim AS runtime +ARG APP_VERSION=0.0.0.0 +ENV NODE_ENV=production \ + NEXT_TELEMETRY_DISABLED=1 \ + HOSTNAME=0.0.0.0 \ + PORT=3000 \ + APP_VERSION=${APP_VERSION} +WORKDIR /app + +RUN groupadd --system --gid 10001 app && \ + useradd --system --uid 10001 --gid app --no-create-home app + +COPY --from=build --chown=10001:10001 /app/.next/standalone ./ +COPY --from=build --chown=10001:10001 /app/.next/static ./.next/static + +USER 10001:10001 +EXPOSE 3000 + +HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \ + CMD ["node", "-e", "fetch('http://127.0.0.1:'+(process.env.PORT||3000)+'/api/healthz').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"] + +CMD ["node", "server.js"] diff --git a/README.md b/README.md index 03e8fa0..7aa5baa 100644 --- a/README.md +++ b/README.md @@ -347,6 +347,22 @@ Run the production server: pnpm preview ``` +## Container Image + +The repository ships a production `Dockerfile` that builds the Next.js standalone server on Node 24 and runs it as a non-root user (uid 10001) on port 3000. + +```bash +docker build -t stack-api-utilities . +docker run --rm -p 3000:3000 \ + -e STACK_API_UTILITIES_PUBLIC_ORIGIN=http://localhost:3000 \ + stack-api-utilities +``` + +- The server is stateless. Credentials and datasets stay in the browser, and OAuth PKCE state travels in a short-lived cookie, so the container needs no secrets or volumes. +- Set `STACK_API_UTILITIES_PUBLIC_ORIGIN` to the public HTTPS origin when the app runs behind a TLS-terminating proxy, so the OAuth callback URL is correct. +- `GET /api/healthz` returns `{"ok":true}` for liveness and readiness probes. +- The image runs with a read-only root filesystem if `/tmp` and `/app/.next/cache` are writable mounts. + ## License Released under the [MIT License](LICENSE). diff --git a/next.config.mjs b/next.config.mjs index 4678774..e15c618 100644 --- a/next.config.mjs +++ b/next.config.mjs @@ -1,4 +1,8 @@ /** @type {import('next').NextConfig} */ -const nextConfig = {}; +const nextConfig = { + // Emit a self-contained server (.next/standalone) so the container image + // ships only the traced runtime files instead of the full node_modules tree. + output: "standalone", +}; export default nextConfig; diff --git a/src/app/api/healthz/route.ts b/src/app/api/healthz/route.ts new file mode 100644 index 0000000..73309e2 --- /dev/null +++ b/src/app/api/healthz/route.ts @@ -0,0 +1,10 @@ +import { NextResponse } from "next/server"; + +export const runtime = "nodejs"; +export const dynamic = "force-dynamic"; + +// Liveness/readiness probe for container hosting. It only proves the Node +// process is serving requests; it deliberately calls no upstream Stack API. +export async function GET(): Promise { + return NextResponse.json({ ok: true }, { headers: { "cache-control": "no-store" } }); +} diff --git a/src/server/healthzRoute.test.ts b/src/server/healthzRoute.test.ts new file mode 100644 index 0000000..51fbd7d --- /dev/null +++ b/src/server/healthzRoute.test.ts @@ -0,0 +1,16 @@ +import { describe, expect, it } from "vitest"; +import { GET as handleHealthzGet, dynamic } from "../app/api/healthz/route"; + +describe("GET /api/healthz", () => { + it("reports the process as healthy without caching", async () => { + const response = await handleHealthzGet(); + + expect(response.status).toBe(200); + expect(response.headers.get("cache-control")).toBe("no-store"); + await expect(response.json()).resolves.toEqual({ ok: true }); + }); + + it("is never statically prerendered", () => { + expect(dynamic).toBe("force-dynamic"); + }); +});