fix(docker): install node-gyp toolchain in build stage for blocked prebuilt downloads (#2148)

better-sqlite3 installs via `prebuild-install || node-gyp rebuild`. The
prebuilt binary is fetched from GitHub Releases, which corporate proxies
and offline mirrors commonly block. The fallback then compiles from
source and dies in node:22-slim because no compiler toolchain is
present. Install python3/make/g++ in the deps stage only; the runtime
image starts from a fresh node:22-slim and is unaffected.

Also documents the same failure mode in the Node.js deployment guide and
clarifies that the guide's Dockerfile (single site) and the repo-root
Dockerfile (monorepo) are different scenarios.

Follow-up to #2132 (#2118).

Author: swissky

Dockerfile

@@ -6,6 +6,16 @@ WORKDIR /app
 # ---- Install dependencies ----
 FROM base AS deps
 
+# Toolchain for the node-gyp fallback of native deps. better-sqlite3 installs
+# via `prebuild-install || node-gyp rebuild`; the prebuilt binary comes from
+# GitHub Releases, which corporate proxies and offline mirrors commonly block.
+# The fallback then compiles from source and needs python3/make/g++, which
+# node:22-slim doesn't ship. Build stages only -- the runtime image below
+# starts from a fresh node:22-slim and is unaffected.
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends python3 make g++ \
+    && rm -rf /var/lib/apt/lists/*
+
 COPY pnpm-lock.yaml pnpm-workspace.yaml package.json ./
 # pnpm-workspace.yaml declares patchedDependencies -> patches/, which pnpm
 # reads during install. It must be in the deps stage or --frozen-lockfile

docs/src/content/docs/deployment/nodejs.mdx

@@ -117,6 +117,30 @@ CMD ["node", "./dist/server/entry.mjs"]
 
 The seed file is read at build time and inlined into the bundle, so it does not need to be copied into the runtime image. Migrations run on the first request after a deploy; the seed applies only when the database has no collections and setup hasn't been completed — existing data is never overwritten.
 
+<Aside>
+	This Dockerfile builds **your own EmDash site** — a project that has `emdash` as a dependency. It is
+	not interchangeable with the `Dockerfile` in the root of the EmDash repository, which builds the whole
+	pnpm monorepo and packages the blog template from source.
+</Aside>
+
+<Aside type="caution" title="Native dependencies behind restrictive networks">
+	EmDash's SQLite driver (`better-sqlite3`) installs a prebuilt binary downloaded from GitHub Releases.
+	If your build environment blocks that download (corporate proxy, offline mirror), the install falls
+	back to compiling from source and fails with a `gyp ERR! find Python` error, because slim/alpine Node
+	images ship no compiler toolchain.
+</Aside>
+
+If you hit that error, install the toolchain in the builder stage before `npm ci`:
+
+```dockerfile
+# Alpine-based images (node:22-alpine)
+RUN apk add --no-cache python3 make g++
+
+# Debian-based images (node:22-slim)
+RUN apt-get update && apt-get install -y --no-install-recommends python3 make g++ \
+    && rm -rf /var/lib/apt/lists/*
+```
+
 Build the image and run the container:
 
 ```bash