ci(docker): smoke test compose stack

Author: AlisinaDevelo

.github/workflows/ci.yml

@@ -68,8 +68,15 @@ jobs:
     steps:
       - uses: actions/checkout@v5
 
+      - uses: actions/setup-node@v5
+        with:
+          node-version: "22"
+
       - uses: docker/setup-buildx-action@v4
 
+      - name: Docker Compose smoke
+        run: npm run smoke:docker
+
       - uses: docker/build-push-action@v7
         with:
           context: .

CHANGELOG.md

@@ -17,6 +17,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Cache resilience for article searches: cache read/write failures are logged and metriced without failing requests.
 - In-flight coalescing for identical cache misses so concurrent same-key searches share one upstream request per process.
 - Redocly-powered `npm run contract` check for the OpenAPI document, wired into CI.
+- Docker Compose smoke test against a fake GNews provider, wired into CI.
 
 ### Security
 

README.md

@@ -124,6 +124,7 @@ Errors: `{ "error": "message" }`. Rate limit: `429` with standard rate-limit hea
 | `npm run lint` | ESLint. |
 | `npm run contract` | Validate `docs/openapi.yaml` with Redocly CLI. |
 | `npm run smoke` | Curl-based smoke test against a running instance (`BASE_URL`, `QUERY`, `COUNT`, optional `CLIENT_API_KEY`). |
+| `npm run smoke:docker` | Compose smoke test: boot the image against a fake GNews provider and run `npm run smoke`. |
 | `npm run benchmark:local` | Builds the app, starts a fake GNews provider, and measures cold searches vs warm cache hits. See [docs/BENCHMARKS.md](docs/BENCHMARKS.md). |
 
 ## Project layout

docker-compose.ci.yml

@@ -0,0 +1,30 @@
+services:
+  fake-gnews:
+    image: node:22-alpine
+    working_dir: /app
+    command: ["node", "/app/scripts/fake-gnews-provider.mjs"]
+    environment:
+      PORT: "4010"
+      FAKE_GNEWS_DELAY_MS: "5"
+    volumes:
+      - ./scripts:/app/scripts:ro
+    healthcheck:
+      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:4010/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
+      interval: 2s
+      timeout: 2s
+      retries: 15
+
+  api:
+    build: .
+    depends_on:
+      fake-gnews:
+        condition: service_healthy
+    ports:
+      - "3000:3000"
+    environment:
+      GNEWS_API_KEY: ci
+      GNEWS_BASE_URL: http://fake-gnews:4010
+      PORT: "3000"
+      NODE_ENV: production
+      DISABLE_RATE_LIMIT: "1"
+      LOG_LEVEL: silent

docs/CI.md

@@ -17,19 +17,20 @@ The [workflow](../.github/workflows/ci.yml) runs on `ubuntu-latest` with **Node.
 
 ### Container (`docker` job)
 
-9. **Buildx build** — [Dockerfile](../Dockerfile) with **`provenance: mode=max`** and **SBOM** (no registry push). Validates supply-chain metadata generation in CI.
+9. **`npm run smoke:docker`** — Compose boots the production image against a GNews-compatible fake provider, waits for readiness, then runs `npm run smoke` against the exposed API.
+10. **Buildx build** — [Dockerfile](../Dockerfile) with **`provenance: mode=max`** and **SBOM** (no registry push). Validates supply-chain metadata generation in CI.
 
 ### Pull requests only
 
-10. **[Dependency review](../.github/workflows/dependency-review.yml)** — flags vulnerable or blocked dependencies introduced by the PR.
+11. **[Dependency review](../.github/workflows/dependency-review.yml)** — flags vulnerable or blocked dependencies introduced by the PR.
 
 ### Every push / PR (supply chain)
 
-11. **[SBOM](../.github/workflows/supply-chain.yml)** — [Anchore SBOM Action](https://github.com/anchore/sbom-action) produces SPDX JSON and uploads it as a workflow artifact.
+12. **[SBOM](../.github/workflows/supply-chain.yml)** — [Anchore SBOM Action](https://github.com/anchore/sbom-action) produces SPDX JSON and uploads it as a workflow artifact.
 
 ### `main` branch pushes only
 
-12. **[Provenance](../.github/workflows/provenance.yml)** — [build provenance attestation](https://github.com/actions/attest-build-provenance) for `package-lock.json` (best-effort; `continue-on-error` if attestations are unavailable on the plan).
+13. **[Provenance](../.github/workflows/provenance.yml)** — [build provenance attestation](https://github.com/actions/attest-build-provenance) for `package-lock.json` (best-effort; `continue-on-error` if attestations are unavailable on the plan).
 
 ### Code scanning (`CodeQL` workflow)
 
@@ -53,6 +54,7 @@ npm run contract
 npm test
 npm run build
 docker build .
+npm run smoke:docker
 ```
 
 Optional (matches the CI Docker job more closely, requires Buildx):

docs/OPERATIONS.md

@@ -84,6 +84,12 @@ CLIENT_API_KEY=client-secret-one npm run smoke
 
 The smoke test checks `/health`, `/ready`, `/openapi.yaml`, `/api/articles`, and `/metrics`.
 
+To smoke-test the production container without a live GNews key, boot the CI Compose stack against the fake provider:
+
+```bash
+npm run smoke:docker
+```
+
 ## Local Benchmark
 
 For reproducible cache/upstream performance checks without a live GNews key:

package.json

@@ -16,6 +16,7 @@
     "lint": "eslint src test vitest.config.ts",
     "contract": "redocly lint docs/openapi.yaml",
     "smoke": "sh scripts/smoke-test.sh",
+    "smoke:docker": "sh scripts/docker-compose-smoke.sh",
     "benchmark:local": "npm run build && node scripts/local-benchmark.mjs"
   },
   "keywords": [

scripts/docker-compose-smoke.sh

@@ -0,0 +1,36 @@
+#!/bin/sh
+set -eu
+
+COMPOSE_FILE="${COMPOSE_FILE:-docker-compose.ci.yml}"
+PROJECT_NAME="${COMPOSE_PROJECT_NAME:-news-api-ci}"
+BASE_URL="${BASE_URL:-http://127.0.0.1:3000}"
+
+cleanup() {
+  status=$?
+  if [ "$status" -ne 0 ]; then
+    docker compose -f "$COMPOSE_FILE" -p "$PROJECT_NAME" logs --no-color || true
+  fi
+  docker compose -f "$COMPOSE_FILE" -p "$PROJECT_NAME" down -v --remove-orphans || true
+  exit "$status"
+}
+
+trap cleanup EXIT
+
+docker compose -f "$COMPOSE_FILE" -p "$PROJECT_NAME" up --build -d
+
+attempt=1
+while [ "$attempt" -le 30 ]; do
+  if curl -fsS "$BASE_URL/ready" >/dev/null 2>&1; then
+    break
+  fi
+
+  if [ "$attempt" -eq 30 ]; then
+    echo "FAIL api did not become ready at $BASE_URL"
+    exit 1
+  fi
+
+  attempt=$((attempt + 1))
+  sleep 2
+done
+
+BASE_URL="$BASE_URL" QUERY="${QUERY:-ci-smoke}" COUNT="${COUNT:-3}" npm run smoke

scripts/fake-gnews-provider.mjs

@@ -0,0 +1,52 @@
+import http from "node:http";
+
+const port = Number(process.env.PORT ?? 4010);
+const delayMs = Number(process.env.FAKE_GNEWS_DELAY_MS ?? 0);
+
+function articleFor(query, index) {
+  return {
+    title: `${query} headline ${index + 1}`,
+    description: `Synthetic article ${index + 1} for ${query}`,
+    content: `Synthetic content for ${query}`,
+    url: `https://example.test/news/${encodeURIComponent(query)}/${index + 1}`,
+    image: null,
+    publishedAt: "2026-01-01T00:00:00.000Z",
+    source: {
+      name: "CI News",
+      url: "https://example.test",
+    },
+  };
+}
+
+function sendJson(res, status, body) {
+  res.writeHead(status, { "content-type": "application/json" });
+  res.end(JSON.stringify(body));
+}
+
+const server = http.createServer((req, res) => {
+  const url = new URL(req.url ?? "/", "http://127.0.0.1");
+
+  if (url.pathname === "/health") {
+    sendJson(res, 200, { status: "ok" });
+    return;
+  }
+
+  if (url.pathname !== "/search") {
+    sendJson(res, 404, { error: "not found" });
+    return;
+  }
+
+  const query = url.searchParams.get("q") ?? "news";
+  const count = Math.max(1, Math.min(Number(url.searchParams.get("max") ?? 3), 100));
+  const articles = Array.from({ length: count }, (_, index) => articleFor(query, index));
+
+  setTimeout(() => sendJson(res, 200, { articles }), delayMs);
+});
+
+server.listen(port, "0.0.0.0", () => {
+  console.log(`fake GNews provider listening on ${port}`);
+});
+
+process.on("SIGTERM", () => {
+  server.close(() => process.exit(0));
+});