Skip to content

OpenPanel is an open-source web and product analytics platform, an open-source alternative to Mixpanel with optional self-hosting.

ralph(M10-008): Image installs only @openpanel/api's workspace closure (pnpm deploy / filtered install); sizes measured both ways

ralphd3988c48395a
diff --git a/apps/api/Dockerfile b/apps/api/Dockerfile
index d12c90323..b6be11d20 100644
--- a/apps/api/Dockerfile
+++ b/apps/api/Dockerfile
@@ -48,7 +48,20 @@ WORKDIR /app
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
# Apps
COPY apps/api/package.json ./apps/api/
-# Packages — @openpanel/api's workspace closure, exactly.
+# Packages — @openpanel/api's workspace closure, exactly as pnpm computes it
+# (verified against `pnpm --filter "@openpanel/api..." list --depth -1`: these
+# 11, plus the private tooling/typescript devDependency, which --prod below
+# never installs, so its manifest is deliberately not copied here). This list
+# is still hand-maintained: Docker's COPY only accepts a glob for the *last*
+# path segment, so `packages/*/package.json` flattens every match into one
+# `packages/package.json`, overwriting instead of preserving each
+# subdirectory — there is no wildcard that copies these into their own
+# directories. `--filter "@openpanel/api..."` below is the actual
+# closure boundary; if a manifest is missing here, the install below does
+# NOT fail loud — it silently omits that package from `node_modules`
+# (surfacing later as a runtime "Cannot find module", not a build failure) —
+# so keep this list in sync with the filter output when api's dependency
+# graph changes.
COPY packages/core/package.json packages/core/
COPY packages/db/package.json packages/db/
COPY packages/trpc/package.json packages/trpc/
@@ -88,9 +101,23 @@ RUN pnpm codegen
# purge an existing devDependency-laden modules dir (verified empirically —
# it left every devDependency in place), so shipping node_modules must come
# from an install that was production-only from the start.
+#
+# `--filter "@openpanel/api..."` (the three-dot suffix: api plus everything it
+# depends on, direct or transitive) is the actual closure boundary, chosen
+# over `pnpm deploy` — deploy needs either `inject-workspace-packages=true`
+# (a repo-wide install-behavior change, out of scope here) or `--legacy`
+# (which re-resolves the full 26-project lockfile graph every build, ~8x
+# slower than a scoped install, for the same output). Verified empirically
+# against this workspace: with only the manifests above present, plain
+# `pnpm install --frozen-lockfile --prod` and this filtered form produce
+# byte-identical node_modules (same 1039 packages) — the manifest list
+# already happened to equal the closure. The filter is kept anyway as the
+# explicit, fails-closed boundary: it is what makes "only api's closure"
+# a property of the command instead of an accident of which package.json
+# files got copied above.
FROM toolchain AS prod-deps
-RUN pnpm install --frozen-lockfile --prod && \
+RUN pnpm --filter "@openpanel/api..." install --frozen-lockfile --prod && \
pnpm rebuild && \
pnpm store prune
diff --git a/docs/OPS_DEPLOY_MIGRATION.md b/docs/OPS_DEPLOY_MIGRATION.md
index 823a2bde5..b8b48ce39 100644
--- a/docs/OPS_DEPLOY_MIGRATION.md
+++ b/docs/OPS_DEPLOY_MIGRATION.md
@@ -208,3 +208,149 @@ $ curl -s http://127.0.0.1:3333/healthz/ready
`bun run start` (apps/api's own package.json script, the `pnpm start`
replacement) was also exercised directly and shut down cleanly on `SIGTERM`
("Graceful shutdown completed").
+
+## M10-008: closure-scoped install (TECH_DEBT §5d)
+
+TECH_DEBT §5d, sourced from M9-006's own "real lever left on the table" note,
+claimed the `prod-deps` stage's workspace-root `pnpm install --frozen-lockfile
+--prod` installed all 23 workspace projects' production dependencies —
+`next`, `react-email`, `@polar-sh/sdk`, `effect`, `mathjs`, ~1.1GB total —
+because it runs at the repo root regardless of which `package.json` files were
+selectively `COPY`'d.
+
+**That diagnosis does not survive `pnpm why`.** Rechecked in this attempt: the
+`toolchain` stage's manifest list already limits pnpm's visible workspace to
+14 projects (root + api + the 11 packages + `tooling/typescript` — `apps/start`
+and `apps/public` are never copied in, so pnpm's workspace glob simply cannot
+see them, confirmed via `Scope: all 14 workspace projects` in the install log
+and by reproducing the exact stage in a scratch directory). Every package named
+in TECH_DEBT §5d is a genuine transitive **production** dependency already
+inside `@openpanel/api`'s real closure, not workspace leakage:
+
+| Package | `pnpm why` chain |
+|---|---|
+| `next`, `react-email` | `@openpanel/email → responsive-react-email → react-email → next` |
+| `effect` | `@openpanel/db → @prisma/client`/`prisma-json-types-generator → @prisma/config → effect` |
+| `mathjs` | `@openpanel/common`, `@openpanel/core`, `@openpanel/trpc` (all direct) |
+| `@polar-sh/sdk` | `@openpanel/payments` (direct) |
+
+`pnpm --filter "@openpanel/api..." list --depth -1` (the real dependency-graph
+closure) returns exactly the same 13 projects (12 packages + `apps/api`) the
+Dockerfile's manifest list already names — confirmed by diffing the resulting
+`node_modules/.pnpm` entries between the current (manifest-only) install and a
+`--filter`-scoped install run against the **full** 26-project manifest set:
+byte-identical, 1039 packages both ways.
+
+### What changed and why
+
+**Command chosen: `pnpm --filter "@openpanel/api..." install --frozen-lockfile
+--prod`**, not `pnpm deploy`. Tested both: `pnpm deploy` needs either
+`inject-workspace-packages=true` (a repo-wide `.npmrc` behavior change, out of
+this task's scope — it would flip every install in the monorepo from symlinked
+to hard-copied workspace deps) or `--legacy` (which works, but re-resolves the
+*entire* 26-project lockfile graph every build — measured 27.6s vs the filtered
+install's 3–15s in-container — for byte-identical output). The filtered
+`install` keeps the existing workspace layout the runtime stage already expects
+(`node_modules` at the project root, symlinks into `packages/*`), so the
+`runtime` stage's `COPY --from=prod-deps` lines needed no changes. ADR-014
+stands: still pnpm, no bun install.
+
+**The per-package `COPY packages/*/package.json` manifest (lines ~51-74) is
+kept, not replaced** — stated plainly per the task's instruction, not silently
+carried over. Docker's `COPY` only globs the final path segment:
+`COPY packages/*/package.json packages/` flattens every match into one
+`packages/package.json`, overwriting rather than preserving each package's own
+directory (verified with a throwaway `alpine` Dockerfile). There is no
+wildcard-COPY that reproduces per-directory manifests, so reaching a
+manifest-free build would mean copying full source before installing
+(`COPY . .`) and losing the existing manifest-only Docker cache layer for the
+dependency-install step entirely — a real regression in iteration speed for a
+correctness property (`--filter` on an already-correct closure) that measures
+as a no-op today. Not taken.
+
+What the `--filter` **does** buy, since the manifest list turned out to
+already be correct: the closure is now a property the install command asserts
+(`--filter "@openpanel/api..."`), not an accident of which files happened to be
+`COPY`'d. If a future PR adds a new package to `apps/api`'s dependency graph
+without adding its manifest line, the install now silently omits it from
+`node_modules` exactly as before (Docker's per-file COPY still requires the
+manifest to exist on disk — `--filter` cannot discover a manifest that was
+never copied) — this is an unfixed, pre-existing risk, called out at the top
+of the `toolchain` stage's comment block, not solved by this task.
+
+### Measured sizes — BEFORE and AFTER, both built in this attempt (2026-09-06)
+
+Command run identically for both: `docker build -f apps/api/Dockerfile -t
+<tag> .`. BEFORE is a **fresh rebuild** of the Dockerfile as it stood at
+`49a6388e` (M10-007's `HEAD`, unchanged since M9-006 — confirmed via `git log
+-- apps/api/Dockerfile`), not the pre-existing `openpanel-v2:slim` tag, so
+both numbers below come from builds this attempt actually ran. Compressed via
+`docker image inspect <tag> --format '{{.Size}}'` (this box's containerd
+snapshotter reports compressed content size, per M9-006); uncompressed via
+`docker images` `DISK USAGE`.
+
+| Image | Tag | Compressed (bytes) | Compressed (MB) | Uncompressed (`docker images` DISK USAGE) |
+|---|---|---:|---:|---:|
+| Before (root `--prod` install, unchanged Dockerfile, rebuilt this attempt) | `openpanel-v2:before` | 341,068,228 | 341.1 | 1.79GB |
+| After (`--filter "@openpanel/api..."` install, this attempt) | `openpanel-v2:closure` | 341,063,856 | 341.1 | 1.79GB |
+
+**Verdict: no measurable size change (−4,372 bytes, noise).** This is the
+correct, honestly-reported result given the `pnpm why` findings above — the
+image was already scoped to `@openpanel/api`'s real closure before this task,
+so there was no apps/start/apps/public dependency bloat to remove. TECH_DEBT
+§5d's premise was wrong; this task's value is making the closure boundary an
+explicit property of the install command instead of an implicit consequence of
+the manifest list, which is a correctness/robustness improvement, not a size
+one. `docs/TECH_DEBT.md` §5d should be corrected to reflect this the next time
+it's touched — not done here, out of this task's scope (register the finding,
+don't edit the register's narrative text as a side effect of closing it).
+
+### Boot proof (2026-09-06, this attempt, against `openpanel-v2:closure`)
+
+```
+$ docker run -d --network host --env-file <env> openpanel-v2:closure # ROLE=api (API_PORT=3333)
+{"...","msg":"API listening","role":"api","port":3333}
+$ curl -s http://127.0.0.1:3333/healthcheck
+{"ready":true,"redis":true,"db":true,"ch":true,"failedDependencies":[],"workingDependencies":["redis","db","ch"]}
+
+$ docker run -d --network host --env-file <env> -e ROLE=worker -e API_PORT=3334 openpanel-v2:closure
+{"...","msg":"worker started","queue":"sessions"} … (all 7 queues) …
+{"...","msg":"kafka consumer joined group (rebalance complete)"}
+{"...","msg":"kafka events consumer running","topic":"events"}
+{"...","msg":"API listening","role":"worker","port":3334}
+$ curl -s http://127.0.0.1:3334/healthcheck
+{"ready":true,"redis":true,"db":true,"ch":true,"failedDependencies":[],"workingDependencies":["redis","db","ch"]}
+```
+
+Self-hosting compose commands (M9-006's `docker-compose.template.yml` /
+`coolify.yml` / `.github/smoke/docker-compose.yml`), run inside
+`openpanel-v2:closure` against this box's local Postgres/ClickHouse:
+
+```
+$ docker exec <container> sh -c "cd /app/packages/db && ./node_modules/.bin/prisma migrate deploy"
+153 migrations found in prisma/migrations
+No pending migrations to apply.
+
+$ docker exec <container> sh -c "cd /app/packages/core && ./node_modules/.bin/jiti src/code-migrations/migrate.ts"
+… ✅ Already Migrated ✅ …
+Migrations finished
+
+$ docker run --entrypoint sh openpanel-v2:closure -c "cd /app/apps/api && bun run start"
+{"...","msg":"API listening","role":"api","port":3335}
+$ curl -s http://127.0.0.1:3335/healthcheck
+{"ready":true,"redis":true,"db":true,"ch":true,"failedDependencies":[],"workingDependencies":["redis","db","ch"]}
+```
+
+All three commands resolve and run unmodified inside the closure-scoped image.
+
+### Cleanup
+
+Tags created in this attempt beyond the required before/after pair: none —
+only `openpanel-v2:before` and `openpanel-v2:closure` were built. Both are
+kept on disk per the task's acceptance (the before/after pair); no other tag
+was created. Pre-existing tags `openpanel-v2:slim` and `openpanel-v2:test`
+(from M9-005/M9-006, untouched by this task) were left as found. This box had
+~16G free before this attempt; four `openpanel-v2:*` tags at ~1.8GB on-disk
+each is within that budget, but if disk pressure appears, `openpanel-v2:slim`
+and `openpanel-v2:test` are the pre-existing tags to reclaim first (this task
+did not create them and does not need them kept).