docs: add OKF_Nuxt decision records and log
PR Check / Security scan (Snyk) (pull_request) Skipped
PR Check / ESLint (pull_request) Successful in 35s
PR Check / Typecheck (pull_request) Successful in 38s
PR Check / Secret scan (gitleaks) (pull_request) Successful in 5s
PR Check / Dependency audit (pull_request) Failing after 8s
PR Check / Dockerfile lint (droast) (pull_request) Failing after 5s
PR Check / AI code review (opencode) (pull_request) Canceled after 16s
PR Check / Security scan (Snyk) (pull_request) Skipped
PR Check / ESLint (pull_request) Successful in 35s
PR Check / Typecheck (pull_request) Successful in 38s
PR Check / Secret scan (gitleaks) (pull_request) Successful in 5s
PR Check / Dependency audit (pull_request) Failing after 8s
PR Check / Dockerfile lint (droast) (pull_request) Failing after 5s
PR Check / AI code review (opencode) (pull_request) Canceled after 16s
This commit is contained in:
1 parent
9987d6b8e4
commit
bb0ab03a97
9 files changed
+390
No files matched your search
@@ -0,0 +1,57 @@
|
||||
---
|
||||
type: Decision
|
||||
title: Build layer order
|
||||
description: Manifests are copied and installed before any source, so a source edit cannot invalidate the dependency install.
|
||||
tags: [decision, docker, caching]
|
||||
status: stable
|
||||
generated: { by: opencode/deepseek-v4.1-flash, at: 2026-10-18T12:41:52Z }
|
||||
verified: { by: human:noel, at: 2026-10-18T12:41:52Z }
|
||||
sources:
|
||||
- id: docker-cache
|
||||
resource: https://docs.docker.com/build/cache/
|
||||
title: Docker build cache
|
||||
---
|
||||
|
||||
# Decision
|
||||
|
||||
Order the instructions so that the things that change rarely are installed
|
||||
first, and the things that change constantly are copied last.
|
||||
|
||||
1. Base image, then the toolchain (`pnpm`).
|
||||
2. `COPY` the manifests only — `package.json`, `pnpm-lock.yaml`, `pnpm-workspace.yaml`.
|
||||
3. `pnpm install --frozen-lockfile`.
|
||||
4. (In an image that copies source at all) `COPY` the source, then build.
|
||||
|
||||
# Why
|
||||
|
||||
Each instruction is a layer, and a change in one layer invalidates that layer and
|
||||
every layer after it. The install is the slow step, so anything that changes
|
||||
often — the source — has to sit after it. Copying the whole source before
|
||||
installing would make every source edit re-run the install, which is exactly the
|
||||
cost the ordering is meant to avoid.
|
||||
|
||||
# What invalidates what
|
||||
|
||||
| Change | Effect |
|
||||
|---|---|
|
||||
| Edit `app/app.vue` | Nothing. In the dev image the source is never copied, so no layer depends on it. |
|
||||
| Edit `package.json`, `pnpm-lock.yaml` or `pnpm-workspace.yaml` | The `COPY` of the manifests and the install after it re-run; earlier layers stay cached. |
|
||||
| Change the pinned base image or the `pnpm` version | Everything from that instruction onward re-runs. |
|
||||
|
||||
# Evidence
|
||||
|
||||
The second consecutive `docker build -f Dockerfile.dev` reported every layer as
|
||||
`CACHED`, and the context transfer was 108 bytes — it contains only the three
|
||||
manifests, so no source edit can reach any layer.
|
||||
|
||||
# Not chosen
|
||||
|
||||
An earlier draft of the dev file ended with `COPY . . --cache` and
|
||||
`pnpm build`. The `COPY` instruction has no `--cache` flag, so that line is a
|
||||
build error, and building the application into a dev image works against running
|
||||
the dev server from a mounted source.
|
||||
|
||||
# Revisit when
|
||||
|
||||
The project gains a second package with its own manifest, which changes what
|
||||
belongs in the manifests-only copy.
|
||||
Reference in new issue
Block a user