@alxia/create 0.1.3 → 0.1.4

package/README.md

@@ -28,8 +28,8 @@ bun create @alxia my-site --template react-router
 
 | template | what it writes |
 | --- | --- |
-| `api` | an `@alxia/core` app with Zod: `POST /todos` validates its body, behind `requireKey`, a hook made with `defineHook` that answers 401 without an API key; a `bun test` spec calling it with `app.request()` and through `@alxia/client`, typed; `bun dev` restarting on change, `typecheck`, `build`, a strict `tsconfig.json`, a `Dockerfile` on `oven/bun:1`, `.dockerignore`, `.gitignore`, `.env.example` and a README |
-| `react-router` | React Router's official template, as `create-react-router` writes it, shipped in this package and copied, with [`@alxia/react-router`](https://www.npmjs.com/package/@alxia/react-router) added as its README says: `alxia()` in `vite.config.ts`'s plugins, `start` running `bun build/server/index.js`, a `bunfig.toml` starting React Router's CLI on Bun, and a `Dockerfile` on `oven/bun:1` in place of React Router's Node one. No server file: the default one serves the pages; `bunx alxia-react-router reveal` writes it out to customise |
+| `api` | an `@alxia/core` app with Zod: `POST /todos` validates its body, behind `requireKey`, a hook made with `defineHook` that answers 401 without an API key; a `bun test` spec calling it with `app.request()` and through `@alxia/client`, typed; `bun dev` restarting on change, `typecheck`, `build`, a strict `tsconfig.json`, a `Dockerfile` running on `oven/bun:1-alpine`, `.dockerignore`, `.gitignore`, `.env.example` and a README |
+| `react-router` | React Router's official template, as `create-react-router` writes it, shipped in this package and copied, with [`@alxia/react-router`](https://www.npmjs.com/package/@alxia/react-router) added as its README says: `alxia()` in `vite.config.ts`'s plugins, `start` running `bun build/server/index.js`, a `bunfig.toml` starting React Router's CLI on Bun, and a `Dockerfile` running on `oven/bun:1-alpine` in place of React Router's Node one. No server file: the default one serves the pages; `bunx alxia-react-router reveal` writes it out to customise |
 
 The heart of the `api` project, its route and hook (the whole file, with
 its imports and schemas, is in the [guide](https://github.com/softistx/alxia/blob/develop/packages/create/docs/guide.md#the-api-template)):
@@ -53,8 +53,9 @@ export const app = alxia()
 
 ## Docker
 
-Both projects build into an image as they are written, on `oven/bun:1`,
-the image running the app as the non-root `bun` user. Each `Dockerfile`
+Both projects build into an image as they are written: built on
+`oven/bun:1`, run on `oven/bun:1-alpine` as the non-root `bun` user, an
+image of about 130 MB. Each `Dockerfile`
 builds in a stage of its own, and the image holds the build output alone,
 no `node_modules`:
 
@@ -81,7 +82,9 @@ with `--frozen-lockfile`. The
 [guide](https://github.com/softistx/alxia/blob/develop/packages/create/docs/guide.md#docker)
 has the stages, and
 [troubleshooting](https://github.com/softistx/alxia/blob/develop/packages/create/docs/troubleshooting.md#error-cannot-find-package--from-appdistserverjs)
-what to do for a dependency that cannot be bundled.
+what to do for a dependency that cannot be bundled, and for a
+[native addon built for glibc alone](https://github.com/softistx/alxia/blob/develop/packages/create/docs/troubleshooting.md#error--is-linked-against-glibc-dt_needed-libmso6-but-this-bun-build-uses-musl),
+which does not load on Alpine.
 
 ## Options
 

package/docs/guide.md

@@ -67,10 +67,10 @@ my-api/
 ├── src/
 │   ├── app.ts        the app, and its type
 │   ├── app.spec.ts   bun test: app.request() and @alxia/client
-│   └── server.ts     app.listen(PORT)
+│   └── server.ts     app.listen(PORT), stopped on SIGTERM
 ├── package.json
 ├── tsconfig.json
-├── Dockerfile        bun run build, then dist/ alone, on oven/bun:1
+├── Dockerfile        bun run build, then dist/ alone, on oven/bun:1-alpine
 ├── .dockerignore
 ├── .env.example      PORT and API_KEY, for a .env Bun loads
 ├── .gitignore
@@ -230,15 +230,25 @@ goes from there.
 
 ## Docker
 
-Each project's `Dockerfile` runs it on Bun, on the official `oven/bun:1`
-image, as the image's non-root `bun` user. The installs are
+Each project's `Dockerfile` builds it on Bun's official `oven/bun:1`
+image, Debian's, and runs it on `oven/bun:1-alpine`, as that image's
+non-root `bun` user (uid 1000). The installs are
 `--frozen-lockfile`, from the `bun.lock` the command's `bun install`
 wrote: commit it.
 
 Each one builds in a stage of its own, and the image holds the build
 output alone: no `node_modules`, no sources. The dependencies are inside
 the bundle, so the image is the base image and a few hundred kilobytes to
-a few megabytes. A dependency that cannot be bundled is kept external and
+a few megabytes: about 130 MB, where the same build on `oven/bun:1` is
+about 345 MB.
+
+The build stages stay on Debian: the tools a build runs, Vite's,
+Tailwind's and any package's install script, are tried on glibc first,
+and Alpine saves nothing there, since the stage is not shipped. What is
+shipped is JavaScript, which Bun runs the same on musl. A native addon is
+the exception: one built for glibc alone cannot load on Alpine, and the
+final stage goes back to `oven/bun:1`
+([troubleshooting](troubleshooting.md#error--is-linked-against-glibc-dt_needed-libmso6-but-this-bun-build-uses-musl)). A dependency that cannot be bundled is kept external and
 copied in: see
 [troubleshooting](troubleshooting.md#error-cannot-find-package--from-appdistserverjs).
 
@@ -250,7 +260,8 @@ Two stages: every dependency, installed with
 running `bun --no-install dist/server.js`, `start`'s command with
 Bun's `--no-install` (not create-alxia's option of the same name), so that a package missing from the bundle fails at
 startup rather than being fetched from npm, written out so that Bun
-is the container's process.
+is the container's process. `src/server.ts` stops the app on `SIGTERM`:
+as process 1, Bun would otherwise ignore it, and `docker stop` would wait.
 
 ```dockerfile
 FROM oven/bun:1 AS build
@@ -260,7 +271,7 @@ RUN bun install --frozen-lockfile
 COPY . .
 RUN bun run build
 
-FROM oven/bun:1
+FROM oven/bun:1-alpine
 WORKDIR /app
 ENV NODE_ENV=production
 COPY --from=build /app/dist ./dist

package/docs/roadmap.md

@@ -30,6 +30,13 @@ Nothing scheduled yet.
 
 ### Next release
 
+- **The images run on Alpine.** Every `Dockerfile`'s final stage is
+  `oven/bun:1-alpine`, the build stages staying on `oven/bun:1`: each
+  image is about 130 MB, where it was about 345 MB. The `api` project
+  stops on `SIGTERM`, so `docker stop` no longer waits.
+
+### 0.1.3
+
 - **Every `Dockerfile` builds, and the image holds the build alone.** The
   `api` template's builds `dist/server.js`, bundled, minified and source
   mapped, and runs it with no `node_modules` and no `src/`; `start` runs
@@ -37,6 +44,9 @@ Nothing scheduled yet.
   copies `build/` alone, which `@alxia/react-router`'s plugin now bundles
   whole. Each image is about 50 MB (api) and 150 MB (react-router)
   smaller.
+
+### 0.1.2
+
 - **The `api` template is files, copied, with a `Dockerfile`.** It ships
   under `templates/api/` and is copied as `react-router`'s is. New in it:
   a `Dockerfile` on `oven/bun:1`, `.dockerignore` and `.env.example`.

package/docs/troubleshooting.md

@@ -38,6 +38,7 @@ nothing — the symptom.
 - [`error: lockfile had changes, but lockfile is frozen`](#error-lockfile-had-changes-but-lockfile-is-frozen)
 - [`error: Module not found "dist/server.js"`](#error-module-not-found-distserverjs)
 - [`error: Cannot find package '…' from '/app/dist/server.js'`](#error-cannot-find-package--from-appdistserverjs)
+- [`error: … is linked against glibc (DT_NEEDED libm.so.6), but this Bun build uses musl.`](#error--is-linked-against-glibc-dt_needed-libmso6-but-this-bun-build-uses-musl)
 - [The project's `@alxia/*` are older than npm's latest](#the-projects-alxia-are-older-than-npms-latest)
 
 ## Before it runs
@@ -325,6 +326,35 @@ COPY --from=production-dependencies /app/node_modules ./node_modules
 the bundle still imports: Node's and Bun's modules, and the packages left
 external.
 
+### `error: … is linked against glibc (DT_NEEDED libm.so.6), but this Bun build uses musl.`
+
+The container stops at startup, or at the first request that loads the
+package, with the path of a `.node` file in `node_modules` and
+`code: "ERR_DLOPEN_FAILED"`. The library named after `DT_NEEDED` is
+whichever one the addon links first: `libc.so.6`, `libstdc++.so.6` or
+another; the fix is the same.
+
+**When:** a package is kept external and installed beside the build, as
+the previous entry says, and it loads a native addon built for glibc
+alone.
+
+**Why:** the final stage is `oven/bun:1-alpine`, whose C library is
+musl. The bundle is JavaScript, which runs the same there, but a `.node`
+file is compiled against one C library, and one compiled for glibc
+cannot load on musl, even with `gcompat`. A package that publishes a
+musl build too, as `sharp` does, works: `bun install`, `--production` too,
+puts both variants in `node_modules`, and the package picks musl's.
+
+**Fix:** run the final stage on Debian's image, `oven/bun:1`, which
+holds glibc. The build stages stay as they are:
+
+```dockerfile
+# The final stage.
+FROM oven/bun:1
+```
+
+The image is about 200 MB larger.
+
 ### The project's `@alxia/*` are older than npm's latest
 
 **Symptom:** a fresh project declares `@alxia/core` at `^0.3.4` while npm

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@alxia/create",
-	"version": "0.1.3",
+	"version": "0.1.4",
 	"description": "Start an alxia app: `bun create @alxia` writes an API with Zod, or React Router's official template served by alxia",
 	"license": "MIT",
 	"type": "module",

package/templates/api/Dockerfile

@@ -14,8 +14,10 @@ RUN bun run build
 # command, written out so that Bun is the container's process, and
 # --no-install: with no node_modules, Bun would otherwise fetch a package
 # the build left out from the registry at startup, where this fails. The
-# server listens on PORT (3000); set API_KEY.
-FROM oven/bun:1
+# server listens on PORT (3000); set API_KEY. On Alpine, about 200 MB
+# lighter: the bundle is JavaScript, which runs the same on musl. A native
+# addon built for glibc alone needs oven/bun:1 here.
+FROM oven/bun:1-alpine
 WORKDIR /app
 ENV NODE_ENV=production
 COPY --from=build /app/dist ./dist

package/templates/api/README.md

@@ -60,13 +60,16 @@ beside `dist/`.
 
 ## Docker
 
-The `Dockerfile` builds in a stage of its own, on `oven/bun:1`: it
+The `Dockerfile` builds in a stage of its own, on `oven/bun:1`, and runs
+on `oven/bun:1-alpine`. The build stage
 installs every dependency with `--frozen-lockfile`, from the `bun.lock`
 that `bun install` wrote (commit it), and runs `bun run build`. The image
 holds `dist/` alone, no `node_modules` and no `src/`, and runs
 `bun --no-install dist/server.js` as its non-root `bun` user: a package
 missing from the bundle fails at startup instead of being fetched from
-npm.
+npm. `src/server.ts` stops the app on `SIGTERM`, so `docker stop` is
+immediate. A native addon built for glibc alone does not load on
+Alpine: put the final stage back on `oven/bun:1`.
 
 ```sh
 docker build -t my-api .

package/templates/api/src/server.ts

@@ -1,4 +1,18 @@
 import { app } from './app';
 
+// Stop as the platform asks. In a container Bun is process 1, which a
+// signal with no handler does not stop: `docker stop` would wait.
+for (const signal of ['SIGINT', 'SIGTERM'] as const) {
+	process.once(signal, () => {
+		void app.stop().then(
+			() => process.exit(0),
+			(error: unknown) => {
+				console.error(error);
+				process.exit(1);
+			},
+		);
+	});
+}
+
 const server = app.listen(Number(Bun.env['PORT'] ?? 3000));
 console.log(`listening on ${server.url}`);

package/templates/react-router/Dockerfile

@@ -16,8 +16,10 @@ RUN bun run build
 # command, and --no-install: with no node_modules, Bun would otherwise
 # fetch a package the build left out from the registry at startup,
 # where this fails.
-# The server listens on PORT (3000) and HOST (0.0.0.0).
-FROM oven/bun:1
+# The server listens on PORT (3000) and HOST (0.0.0.0). On Alpine, about
+# 200 MB lighter: build/ is JavaScript, which runs the same on musl. A
+# native addon built for glibc alone needs oven/bun:1 here.
+FROM oven/bun:1-alpine
 WORKDIR /app
 ENV NODE_ENV=production
 COPY --from=build /app/build ./build