Remaining commit items

doc/deployment-benchmark-and-coolify.md

@@ -0,0 +1,52 @@
+# Deployment Benchmark And Coolify Notes
+
+## Local build timings
+
+Measured on this workstation on 2026-03-21:
+
+- `bun run build` cold-ish run: `26.00s` wall time
+- `bun run build` warm run: `20.68s` wall time
+- Turbopack compile phase inside those runs: `8.8s` cold-ish, `7.8s` warm
+
+Observed repeated work on every build:
+
+- taxonomy generation
+- workflow manifest generation
+- TypeScript validation performed by Next during build
+- static page generation
+
+## Docker attempt
+
+The local Docker daemon did not respond during validation. `docker build` and `docker info` both stalled until externally timed out, so the image could not be run end-to-end on this machine in this session.
+
+That means the application build was validated locally, but container execution still depends on a healthy Docker engine on the target host.
+
+## Changes made for deployment
+
+- Added a `prod-deps` stage so the runtime image uses production dependencies instead of the full development install.
+- Bundled `scripts/bootstrap-production.ts` into `bootstrap-production.js` during image build so the runtime image no longer needs the full TypeScript source tree just to run startup bootstrap.
+- Changed the runtime command to execute the bundled bootstrap directly and then `exec` the standalone Next server.
+- Set `HOSTNAME=0.0.0.0` in the runtime image so direct Dockerfile-based deployments behave correctly without compose overrides.
+- Reduced the Docker build context by excluding docs, tests, local metadata, and `rust/target`.
+
+## Coolify requirements
+
+This project is viable on Coolify if it is deployed as a multi-service Docker Compose stack, not as a single app without Postgres.
+
+Required runtime conditions:
+
+- single replica only
+- persistent Docker volumes for `/app/data` and Postgres data
+- `WORKFLOW_TARGET_WORLD=@workflow/world-postgres`
+- `WORKFLOW_POSTGRES_URL=postgres://workflow:workflow@workflow-postgres:5432/workflow`
+- `DATABASE_URL=file:/app/data/fiscal.sqlite`
+- valid `BETTER_AUTH_SECRET`
+- `BETTER_AUTH_BASE_URL` and `BETTER_AUTH_TRUSTED_ORIGINS` set to the final public Coolify URL
+
+## Highest-impact deployment optimizations
+
+1. Keep build cache warm on the same Coolify builder. The Dockerfile now benefits from Bun dependency cache mounts, a separate production dependency stage, and `.next/cache`.
+2. Avoid invalidating image builds with non-runtime file changes. The updated `.dockerignore` keeps docs, tests, and local artifacts out of the build context.
+3. Consider moving taxonomy generation out of the hot path if the data does not change on every deploy. It currently runs on every application build.
+4. Consider splitting bootstrap responsibilities further if startup latency becomes a problem. Right now startup still performs workflow setup and SQLite migrations before the app binds its port.
+5. If horizontal scaling is required later, move the app database off SQLite. Coolify can run this as-is, but only safely as a single-writer instance.