The monorepo was on npm workspaces. pnpm gives it a content-addressed store
shared between the eight packages, a lockfile that records the whole graph
rather than a flattened view of it, and — the reason this mattered in practice —
`workspace:*`, which makes an internal dependency unambiguous instead of a
version range that npm may satisfy from the registry.
Mechanics:
- `packageManager: pnpm@11.21.0` pins the version; corepack installs it in CI
and in the image, so all three environments resolve identically.
- The npm `workspaces` array is replaced by `pnpm-workspace.yaml`. pnpm
ignores the former, and keeping both would leave two sources of truth.
- All six internal dependencies moved to `workspace:*`.
- Root scripts use `pnpm -r --if-present` and `pnpm -F <pkg>`.
Two findings worth recording, both from running it rather than reading it:
`tsx` was a devDependency, but the server runs TypeScript directly in
production — the container's command is `pnpm exec tsx apps/api/src/server.ts`.
Under npm this was concealed by the runtime stage re-installing tsx by hand
after pruning dev dependencies. Under `pnpm install --prod` that sleight of
hand stops working and the image simply fails to start. tsx is now declared in
`dependencies`, which is what it has always actually been.
The first image build failed with ERR_PNPM_ABORTED_REMOVE_MODULES_DIR_NO_TTY.
That is not a pnpm bug: it had decided the modules directory was stale and
wanted confirmation before deleting it, which a non-interactive build cannot
give. The trigger was the host's `node_modules` reaching the build context —
there was no `.dockerignore` at all. pnpm's tree is symlinks into a
content-addressed store, so copying it into an image produces dangling links
and a directory pnpm rightly considers corrupt. Fixed by adding
`.dockerignore` and setting `CI=true`, which is required in any non-interactive
pnpm build.
`esbuild` is denied install scripts via `allowBuilds`. Its platform binary
arrives through the optional dependency `@esbuild/linux-x64` and the postinstall
only verifies it; confirmed by running the binary directly, which reports
0.25.12.
Verified under pnpm: typecheck clean, 150 tests / 0 failures, e2e passes, web
builds. The image was built and booted against a real Postgres — health ok,
`/api/dashboard` 401 with an issuer configured, `/` and `/capacity` serve the
SPA, `/og.png` serves as image/png, and the migrator runs from the pruned
runtime stage.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
One container plus a Postgres behind any TLS-terminating proxy. Nothing is
specific to a particular host.
The app and API are served from a SINGLE origin. This is not tidiness: browser
auth sessions live in per-origin storage, so splitting them across two
hostnames makes sign-in loop in a way that presents as a server fault. The
short alias redirects rather than serving a second origin.
Two safety properties verified by running the image, not by reading the code:
- With NODE_ENV=production and no SUPABASE_URL, the process refuses to start
and says why. Serving the whole CRM unauthenticated is a worse outcome than
failing to deploy, so the failure is deliberate and loud.
- In production the development auth bypass does not apply: an unauthenticated
request to /api/dashboard returns 401 rather than adopting the first user in
the table.
The Dockerfile typechecks all six packages as a build gate, so a deploy that
does not compile fails at build time rather than in front of a user. Runtime
runs unprivileged as `node`, and Postgres is not published to the host.
Docs cover the ontology and why it is shaped this way, agent connection for
Claude Code / Codex / prime-agent / Buzz, and the provenance rules governing
seed data about real people — including how to have your record removed.
Verified: image builds, container reports healthy, serves the SPA, enforces
auth, and the production guard exits non-zero.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
karti