Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions .dockerignore
Original file line number Diff line number Diff line change
@@ -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
55 changes: 55 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -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
54 changes: 54 additions & 0 deletions Dockerfile
Original file line number Diff line number Diff line change
@@ -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"]
16 changes: 16 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
6 changes: 5 additions & 1 deletion next.config.mjs
Original file line number Diff line number Diff line change
@@ -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;
10 changes: 10 additions & 0 deletions src/app/api/healthz/route.ts
Original file line number Diff line number Diff line change
@@ -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<NextResponse> {
return NextResponse.json({ ok: true }, { headers: { "cache-control": "no-store" } });
}
16 changes: 16 additions & 0 deletions src/server/healthzRoute.test.ts
Original file line number Diff line number Diff line change
@@ -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");
});
});
Loading