feat(demo): one-command Docker demo environment (API/Web/Worker + PrestaShop)

[jakubretajczykBD]

Add a dedicated demo overlay that boots the full OpenLinker stack in Docker with a single command, on top of the existing infra services.

• Dockerfile: new worker build target; also fixes a pre-existing blocker where the ksef/infakt workspace manifests + dist were never copied, so the image build failed outright (unnoticed because CI does not build the image).
• apps/web/Dockerfile + nginx.conf: static SPA build served by nginx with SPA-fallback routing; VITE_API_BASE_URL baked at build time.
• package.json: demo:up / demo:down / demo:logs scripts.
• README.md: demo section (URLs, credentials, manual PS<->OL connection).

Closes #1352

Summary

• One-command Docker demo overlay (pnpm demo:up) that boots API/Worker/Web + PrestaShop on top of the existing infra compose services.
• Addressed all /pr-review findings from @piotrswierzy (2026-07-06): committed .dockerignore, a CI docker build smoke job guarding the Dockerfile's per-package COPY lists, loopback-bound demo ports, nginx gzip/cache/security headers, plus the two remaining suggestions.

Related issues

Closes #1352

Test plan

Fresh clean-volume boot (docker compose … down -v then pnpm demo:up), verified live:

• docker build --target base -f Dockerfile . and docker build -f apps/web/Dockerfile . both succeed from a clean checkout (no host .git/node_modules/dist/*.tsbuildinfo leaking into the build context via the new .dockerignore) — this also caught and fixed a real bug: a host tsconfig.tsbuildinfo copied into the image made tsc -b fail with TS6305 Output file has not been built from source, since the corresponding host dist/ was (correctly) excluded. Adding **/*.tsbuildinfo to .dockerignore fixed it.
• pnpm demo:up on an empty Postgres volume: migrate container ran every migration from scratch and exited 0.
• openlinker-api, openlinker-worker, openlinker-web all reached Up state.
• POST http://localhost:3000/v1/auth/login with admin/admin → 200 with an access token.
• CORS preflight from Origin: http://localhost:8090 → Access-Control-Allow-Origin: http://localhost:8090.
• docker port openlinker-api / openlinker-web → both 127.0.0.1:* only (not 0.0.0.0), confirming the loopback-bind fix.
• Web image: nginx -t passes; GET / returns Cache-Control: no-cache + X-Content-Type-Options/X-Frame-Options/Referrer-Policy; GET /assets/*.js returns Cache-Control: public, immutable + the same security headers (nginx doesn't inherit server-level add_header into a location that sets its own, so they're re-stated per location block — verified by curl, not just config review).
• docker compose … config (with a dummy encryption key) confirms the ports: !override on api resolves to exactly one loopback binding, not two conflicting ones (the naive ports: list under a Compose overlay merges/appends rather than replacing).
• Worker log shows SyncJobRunner starting cleanly with no errors on a fresh DB (no connections configured yet, so no jobs to run — expected for a from-scratch boot).
• Stack torn down afterward (down -v); dev-stack docker-compose.yml itself is untouched, so pnpm dev:stack:up is unaffected by this PR.

Quality gate

• pnpm lint passes (zero errors) — no TypeScript touched by these fixes
• pnpm type-check passes (zero errors) — no TypeScript touched by these fixes
• pnpm test passes (all unit tests green) — no TypeScript touched by these fixes
• Optional, Docker required: pnpm test:integration passes — needed
  only if you touched apps/api/test/integration/** or any plugin's
  infrastructure/adapters/.

Migrations

• If this PR changes an ORM entity, a migration is included under
  apps/api/src/migrations/ (or the plugin package), pnpm --filter @openlinker/api migration:show confirms it's listed, and both
  up() and down() were tested locally. See
  docs/migrations.md. Tick this box for
  PRs that don't touch schemas too — it's trivially satisfied.

ADR

• If this PR makes a non-trivial architectural decision (affects
  multiple contexts, the plugin contract, or has alternatives worth
  documenting), an ADR should be included under
  docs/architecture/adrs/ or referenced in the PR description.
  ADRs are a recommendation, not a hard gate — see
  docs/architecture/adrs/README.md
  § "When to write an ADR" for the decision criteria. Tick this box
  for PRs that don't make architectural decisions too — it's
  trivially satisfied.

DCO sign-off

Sign off every commit with git commit -s. OpenLinker uses the
Developer Certificate of Origin
as its contributor attestation (see
CONTRIBUTING.md → Commits). Automated
enforcement is deferred until after the org transfer; sign off anyway
so the history is consistent when enforcement starts.

Adding a new integration adapter? (expand)

If this PR introduces a new package under libs/integrations/<x>/,
declare its status so reviewers know what bar to apply:

• alpha — experimental; API may change, no production traffic
  yet
• beta — stable contract, real-world use ongoing, breaking
  changes flagged in PR title
• stable — production-ready; breaking changes follow semver

See docs/architecture-overview.md
for the adapter / capability contract and
GOVERNANCE.md for the policy on plugin authors
co-maintaining their own adapter.

UI changes? Attach screenshots at three widths (expand)

Per docs/frontend-ui-style-guide.md § Responsive,
mobile and tablet are first-class. Capture after-shots at all three
breakpoints:

• Mobile (360 × 812):
• Tablet (768 × 1024):
• Desktop (1440 × 900):

---

_{By submitting this pull request, I confirm that my contributions
are made under the terms of the Apache License 2.0, and I
certify the Developer Certificate of Origin
by signing off my commits.}

[piotrswierzy]

/pr-review — systematic review (draft)

Reviewed with an infra/DX lens against the live tree. A well-reasoned, correctly-wired demo overlay — compose merge semantics, boot ordering, the migrate-from-base choice, worker env, and the admin/admin bootstrap short-circuit are all sound. Security sweep is clean (headline check): every credential is demo-scoped and pre-existing in pattern (OL_BOOTSTRAP_ADMIN_PASSWORD=admin short-circuits the prod random-password path deliberately; OL_PII_HASH_SALT is identical to base's; JWT_SECRET is inherited from base, not newly baked; VITE_API_BASE_URL=http://localhost:3000 bakes no private endpoint; no .env tracked). The gaps are DX/reproducibility, not happy-path correctness.

🟡 IMPORTANT — .dockerignore is gitignored, so it never ships

An on-disk .dockerignore exists but .gitignore:64 excludes it, so a fresh git clone (the exact git clone … && pnpm demo:up flow the README headlines) has none. Consequences: (a) every image layer bakes .git + all source; (b) for existing contributors who already ran the dev flow, base's COPY . . (after pnpm install) copies host node_modules/dist over the container tree — host-OS native binaries (esbuild/rollup/bcrypt) break pnpm build/vite build; (c) a local .env gets baked into layers. This PR promotes docker build from an untested future path to the headline UX, so the ignore file becomes necessary. Fix: commit .dockerignore (drop it from .gitignore).

🟡 IMPORTANT — the Dockerfile plugin-copy fix is hardcoded per-package, re-arming the trap it fixes

The unblocking fix adds infakt/ksef to the enumerated per-package COPY package.json + COPY --from=base … dist lists (Dockerfile:27-38, 61-72, 84-95) — it doesn't generalize. The 11th plugin will silently break base's pnpm install again (unresolved workspace:*), the same drift class as #917/#916. CI doesn't build the image, which is why this blocker reached main unnoticed. Fix: add a CI smoke job running docker build --target base . (cheap, catches manifest drift immediately); at minimum comment each list tying it to apps/{api,worker}/package.json deps.

🟡 IMPORTANT — draft with an empty body / no test plan

For infra work whose only validation is manual, the test plan is the evidence of correctness. Fill the body with the executed Phase-4 run log (clean-volume boot, migrate Exited (0), admin/admin login hitting :3000, worker started + one job processed, dev-flow-unaffected check) before marking ready.

🟢 SUGGESTIONS

• docker-compose.demo.yml:66-68 — the demo web (and inherited api) publish to 0.0.0.0, while base compose deliberately binds dev services to loopback. With default admin/admin and no redaction, a multi-homed/LAN host exposes it. Bind 127.0.0.1:8090:80 to match the existing loopback pattern (non-blocking for pure-localhost).
• Dockerfile:67-72 — the worker stage inherits the full API image (apps/api/dist + node_modules it never runs) plus a dev-inclusive worker install. Correct, but bloated; branch from a leaner stage or accept it for a demo.
• docker-compose.demo.yml:4-6 — header example omits phpmyadmin but the real demo:up script includes it; align the comment.
• apps/web/nginx.conf — try_files … /index.html is correct for React Router; no gzip/cache/security headers (fine for a local demo, worth a follow-up if reused for the hosted demo).

Verdict: 🔄 Request changes (draft — expected). Resolve the two IMPORTANT code items (commit .dockerignore, add a docker build CI smoke job) and fill the body with the Phase-4 run log before marking ready. No BLOCKING defects; no security or architecture-boundary issues.

[norbert-kulus-blockydevs]

Addressed all findings from the /pr-review above (commit 6fc0919), including the suggestions, not just the IMPORTANT items:

IMPORTANT

• .dockerignore was gitignored (.gitignore:64), so a fresh clone shipped no ignore rules at all. Committed it (and removed it from .gitignore). While validating this with a real docker build, the fix surfaced a genuine bug: a stray host tsconfig.tsbuildinfo copied into the build context made tsc -b fail with TS6305: Output file has not been built from source, because the corresponding host dist/ is (correctly) excluded but the incremental build state pointing at it wasn't. Added **/*.tsbuildinfo to .dockerignore and re-verified — docker build --target base -f Dockerfile . now succeeds clean.
• Added a docker-build-smoke CI job (.github/workflows/ci.yml) that runs docker build --target base -f Dockerfile . and docker build -f apps/web/Dockerfile . on every code-touching PR, so a plugin added to apps/api/apps/worker without a matching Dockerfile COPY entry fails CI immediately instead of reaching main unnoticed. Also added comments in the Dockerfile tying each enumerated COPY list back to the apps/{api,worker}/package.json deps it mirrors.
• Filled in the PR body's Test plan with the actual clean-volume boot log: migrate ran every migration from scratch and exited 0, api/worker/web all reached Up, admin/admin login returned a 200 with a token, and the stack was torn down afterward.

SUGGESTIONS

• docker-compose.demo.yml: bound both api (3000) and web (8090) to 127.0.0.1 instead of 0.0.0.0, since the demo ships default admin/admin with no redaction. Note: a plain ports: list under a Compose overlay merges/appends rather than replaces, so api needed ports: !override — otherwise the old unbound 3000:3000 and the new loopback binding would coexist and fail to bind the same host port twice (caught this via docker compose config before it reached a real boot).
• Dockerfile: added a comment on the worker stage documenting the accepted bloat (inherits the full API image + a dev-inclusive worker install) as a demo-only tradeoff.
• The compose-header/phpmyadmin comment drift was already fixed by [BUG] Infrastructure — Docker demo (#1352) clean-checkout boot blockers + PrestaShop connection networking gaps #1368's follow-up commits — verified current state matches demo:up's actual service list.
• apps/web/nginx.conf: added gzip, baseline security headers (X-Content-Type-Options, X-Frame-Options, Referrer-Policy), and cache headers (immutable for hashed /assets/*, no-cache for index.html). Verified live with curl — nginx does not inherit server-level add_headers into a location block that sets its own, so each location re-states them explicitly (a real gotcha I hit and fixed, not just a copy-paste from docs).

All of the above was verified against live containers (not just config review): full clean-volume pnpm demo:up, curl against /v1/auth/login, docker port output confirming the loopback binding, and nginx -t + header inspection on the built web image. Full details in the updated Test plan section of the PR description.

[piotrswierzy]

/pr-review — delta re-review (56744330 → 543ab3d2, now ready, base = main)

All three IMPORTANT items from my 2026-07-06 pass are genuinely resolved with committed, CI-verifiable evidence, and both suggestions landed. Clearing my earlier request-changes. (Author's own delta = 2 commits; GitHub's true PR diff is 16 files, all infra/DX.)

✅ Prior IMPORTANTs

1. .dockerignore never shipped → RESOLVED. Now tracked (git ls-tree blob cda5916); excludes .git/, **/node_modules/, **/dist/, **/coverage/, .env+.env.* (with !.env.example), and **/*.tsbuildinfo (the TS6305 catch). The # Docker exclusion block was deleted from .gitignore.
2. Hardcoded plugin-COPY drift trap / no CI guard → RESOLVED. New docker-build-smoke job (ci.yml:326-346) runs docker build --target base and apps/web/Dockerfile — genuinely builds (base runs pnpm install+pnpm build), so a plugin added without a matching COPY fails workspace:* and the job. Gated to run on this PR (Dockerfile changed → code filter true). Source-of-truth comments added to the enumerated lists.
3. Empty body / no test plan → RESOLVED. Substantive from-scratch run log (clean-volume demo:up, migrate exits 0, containers Up, /v1/auth/login→200, CORS echo, docker port confirming loopback-only, nginx -t+per-location header curl, compose config proving !override).

✅ Suggestions confirmed

• Loopback ports: api uses ports: !override → 127.0.0.1:3000:3000 (replaces base rather than appends; also volumes: !reset []); web overlay-only 127.0.0.1:8090:80; OL_CORS_ORIGIN/VITE_API_BASE_URL line up.
• nginx headers: gzip on; X-Content-Type-Options/X-Frame-Options/Referrer-Policy re-stated per-location (correct — server-level add_header isn't inherited once a location sets its own); /assets/ immutable 1y vs / no-cache.

✅ Regression sweep clean

Security: no tracked .env (only placeholder .env.example), demo-scoped throwaway literals now ${VAR:-default}, encryption key required via ${…:?} (fail-closed). Scope: all 16 files infra/DX, no src behavior code. Migrate-then-start gating intact (service_completed_successfully, one-shot migrate), no synchronize.

🟢 SUGGESTION (non-blocking)

The CI smoke build only exercises --target base; the production/worker stages carry a separate enumerated manifest + COPY --from=base .../dist list (Dockerfile:90-103, 125-126) that --target base never runs, so drift there stays uncaught until a full image build. Fine for a demo overlay (the sync comments mitigate) — worth a follow-up.

Verdict: ✅ Approve. Branch is currently behind main — update it before merge.