docs(okf): add Nuxt knowledge bundle in OKF v0.2

Record the design decisions behind the Nuxt site as an OKF v0.2 bundle: dev
container shape, build layer order, build context filter, repository and
compose layout, and the mockup layout, plus the open questions.

Conformant per the spec: every concept carries a non-empty type, the reserved
index and log files follow their structures, and every internal link resolves.
This commit is contained in:
Noel Sabia committed 2026-10-18 14:49:25 +02:00
1 parent 5caa3457aa
commit 8fa078707c
9 files changed
+390

No files matched your search

@@ -0,0 +1,76 @@
---
type: Decision
title: Build context filter
description: The .dockerignore keeps secrets and noise out of the build context, but must never exclude a path the Dockerfile copies.
tags: [decision, docker, dockerignore]
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-context
resource: https://docs.docker.com/build/building/context/
title: Docker build context and .dockerignore files
---
# Decision
Two rules, in this order:
1. **Secrets never enter the build context** — `.env`, `.env.*` (with
`!.env.example` as an exception), `*.pem`, `*.key`, `.npmrc`.
2. **Noise stays out** — `node_modules`, `.nuxt`, `.output`, `.nitro`, `.data`,
`.cache`, `dist`, `*.log`, `coverage`, plus repo and editor metadata.
And one rule that overrides both: **nothing the Dockerfile copies may appear in
the file.** The manifests, `nuxt.config.ts`, `app/`, `public/` and `tsconfig.json`
are deliberately absent.
# Why
`.dockerignore` does not decide what lands in the image; it decides what is sent
to the builder as the build context. What lands in the image is decided by `COPY`
and `RUN`. So the question is never "is this file dangerous to include" but "does
any instruction need this file, and is sending it costing something".
That is what makes the two jobs conflict. A broad list is the right instinct when
the Dockerfile says `COPY . .`, because the list is then the only thing standing
between the working tree and the image. Explicitly copying named manifests
inverts it: the list stops protecting and starts subtracting files the build
asks for.
# The failure mode
Excluding a `COPY` target does not silently skip the file. It warns, then fails
the build. Measured on a scratch context containing only `package.json` and
`pnpm-workspace.yaml`, with `pnpm-workspace.yaml` in the ignore file:
```
- CopyIgnoredFile: Attempting to Copy file "pnpm-workspace.yaml" that is excluded by .dockerignore (line 2)
ERROR: failed to build: failed to solve: failed to compute cache key:
failed to calculate checksum of ref ...: "/pnpm-workspace.yaml": not found
```
The warning names the offending line of `.dockerignore`, which is the useful part:
the failure otherwise reads like a typo in the Dockerfile.
`pnpm-workspace.yaml` is worth calling out because in pnpm 11 it is not only
workspace globs — it carries pnpm settings such as `allowBuilds` and
`minimumReleaseAgeExclude`, so excluding it from a build changes install
behaviour as well as breaking the copy.
# Consequences
* `.npmrc` sits under secrets, so registry configuration has to reach a build
through a build argument rather than the file.
* The excluded `Dockerfile`, `Dockerfile.*` and `.dockerignore` entries are safe:
those files are still sent to the builder because the build needs them, they
simply cannot be copied into the image.
* For the dev image the context is three manifests, so the rest of the list does
nothing there. The size effect it is meant to have lands in an image that does
copy the source.
# Evidence
The second dev build transferred a context of 108 bytes, which is the three
manifests and nothing else. The failure text above was reproduced in a scratch
context so the repository was not modified.
+57
View File
@@ -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.
+89
View File
@@ -0,0 +1,89 @@
---
type: Decision
title: Dev container shape
description: The Nuxt source is bind-mounted into a container that already holds the toolchain and the dependencies, and the dev server runs as the image's node user.
tags: [decision, docker, nuxt, development]
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: node-image
resource: docker.io/library/node:26-slim@sha256:d62f13676d530f7edf97782729df69713c8ccfe6631e7f62f9ccab65968719a8
title: Node 26 slim base image
---
# Decision
`Dockerfile.dev` is a prepared runtime, not a build of the application. It holds
the toolchain and the installed dependencies. The source arrives at run time as a
bind mount, and the container runs the Nuxt dev server. There is no `COPY . .` and
no build step in the dev image.
# Why
The alternative is to copy the source into the image and rebuild on every edit,
which makes each edit cost a full image build. With the source mounted, an edit is
a file write and the dev server's own reload does the rest. The image stops being
something you rebuild and becomes something you run.
# Shape
```dockerfile
FROM node:26-slim@sha256:d62f13676d530f7edf97782729df69713c8ccfe6631e7f62f9ccab65968719a8
# Node no longer bundles pnpm (corepack and pnpm are both absent from this
# image), so install it. First instruction, so later changes reuse the layer.
RUN npm install -g pnpm@11.26.0
# The bind mount lands here at run time, owned by the image's `node` user.
# Its uid 1000 matches the host uid, so files it writes stay yours.
RUN mkdir -p /app && chown node:node /app
USER node
WORKDIR /app
# Manifests only: this layer and the install below survive every source edit
# and re-run only when a manifest changes.
COPY --chown=node:node package.json pnpm-lock.yaml pnpm-workspace.yaml ./
RUN pnpm install --frozen-lockfile
EXPOSE 3000
CMD ["pnpm", "run", "dev", "--", "--host", "0.0.0.0"]
```
| Piece | Choice | Why |
|---|---|---|
| Base image | `node:26-slim`, pinned by digest | The digest makes the build reproducible; the checked digest resolves to Node v26.12.0. |
| pnpm | Installed explicitly, pinned to 11.26.0 | Neither `corepack` nor `pnpm` is present in the image. The pin matches the host version, so the same lockfile format is used on both sides. |
| User | The image's `node` user, uid 1000 | The host uid is also 1000. Files the dev server writes into the mounted repo stay owned by Noel instead of becoming root-owned. This is not a security measure. |
| `node_modules` | Anonymous volume at `/app/node_modules` | The bind mount replaces all of `/app`, which would otherwise hide the dependencies installed in the image. |
| Command | `pnpm run dev -- --host 0.0.0.0` | The dev server would otherwise listen on localhost inside the container and be unreachable from the host. The `--` passes the flag through pnpm to the `dev` script rather than letting pnpm interpret it. |
# Evidence
| Command | Result |
|---|---|
| `docker build -f Dockerfile.dev -t cv-site-nuxt:dev .` | Builds. `esbuild`'s postinstall ran, so the `allowBuilds` setting in `pnpm-workspace.yaml` is honoured. `pnpm install` reported "Lockfile passes supply-chain policies (593 entries)". |
| Same build run a second time | Every layer `CACHED`. |
| `docker run -v <repo>:/app -v /app/node_modules -p 13000:3000 cv-site-nuxt:dev` | `HTTP 200` from the host after 4 seconds; server reported "Ready in 2.02s". |
| `ls -A /app/node_modules` inside that container | 9 entries (`nuxt`, `vue`, `vue-router`, `.pnpm`, …) — the anonymous volume is populated from the image rather than starting empty. |
| Ownership of `.nuxt` on the host after that run | `noel:noel`, so the uid-1000 choice holds. |
# Side effects on the host
The bind mount means Docker resolves the mount point for the `node_modules`
volume through the host directory, so a first run leaves an empty, root-owned
`node_modules` in the repository. It deletes without sudo, and if the directory
already exists the ownership is left alone — a pre-created directory stays
`noel:noel`.
# Not verified
* `docker compose up --build -V` as the remedy for a stale anonymous volume after
a dependency change was not tested.
* That a root-owned `node_modules` breaks a host-side `pnpm install` is inferred
from the permissions, not measured.
# Revisit when
* The container runs on a machine whose uid is not 1000.
* The dev server needs a host port other than 3000.
+7
View File
@@ -0,0 +1,7 @@
# Decisions
* [Dev container shape](dev-container-shape.md) - The source is bind-mounted into a container that already holds the dependencies, and the dev server runs as the image's `node` user.
* [Build layer order](build-layer-order.md) - Why the manifests are copied before the source, and what invalidates what.
* [Build context filter](build-context-filter.md) - What `.dockerignore` may exclude, and the one thing it must never exclude.
* [Repository and compose layout](repo-and-compose-layout.md) - The Dockerfiles live with the app; the stack is assembled in `Local_Development`.
* [Mockup layout](mockup-layout.md) - One `DESIGN.md` per screen, with the screenshot and the source embedded.
+55
View File
@@ -0,0 +1,55 @@
---
type: Decision
title: Mockup layout
description: Every mockup screen folder holds DESIGN.md, code.html and screen.png, with the screenshot and the full source embedded in the markdown.
tags: [decision, design, mockups]
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: stitch-export
resource: Stitch export "resilient_systems_engineer_portfolio", seven screens
title: Stitch export used for the mockups
---
# Decision
Each screen is one folder holding three files, all at the same level:
| File | Role |
|---|---|
| `DESIGN.md` | The screen as a document: frontmatter, the screenshot rendered inline, then the full source in a fenced block. |
| `code.html` | The screen's source, unchanged. |
| `screen.png` | The rendered screenshot, kept separately so it can be opened directly. |
The export's folder names were replaced with short, consistent ones:
| Export name | Folder |
|---|---|
| `noel_sabia_homepage_cv_overview` | `homepage` |
| `noel_sabia_overview_mobile` | `homepage_mobile` |
| `noel_sabia_dev_view_technical_telemetry` | `dev_view` |
| `noel_sabia_dev_view_mobile` | `dev_view_mobile` |
| `noel_sabia_life_map` | `life_map` |
| `noel_sabia_life_map_mobile` | `life_map_mobile` |
| `noel_sabia_infrastructure_ai_resilience` | `design_system` |
# Why
A screen should be readable as one document without opening anything else, which
is what embedding the screenshot and the source gives. Keeping `screen.png` beside
the markdown as well is for looking at the picture on its own, without reading the
document around it.
The frontmatter on `DESIGN.md` — `type`, `title`, `description`, `tags`,
`status` — is also valid concept frontmatter, so these files are readable as
concepts if the mockups are ever folded into a knowledge bundle.
# Notes
* The export shipped `DESIGN.md` and nothing else for the infrastructure folder.
That folder is the design-token document, not a screen, so it deliberately has
no `code.html` and no `screen.png`.
* A second, byte-identical copy of the export was deleted. Equality was checked
file by file with `cmp` across all 13 files before anything was removed.
* Committed as `docs(design): embed screenshot and source into per-screen DESIGN.md`.
@@ -0,0 +1,44 @@
---
type: Decision
title: Repository and compose layout
description: Each application repository owns its Dockerfiles; Local_Development holds the compose file that assembles the stack.
tags: [decision, docker, compose, repositories]
status: stable
generated: { by: opencode/deepseek-v4.1-flash, at: 2026-10-18T12:41:52Z }
sources:
- id: okf-spec
resource: https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md
title: Open Knowledge Format specification, version 0.2
---
# Decision
* `CV_Site_Nuxt/` owns its images: `Dockerfile.dev` and `Dockerfile` live with the
application they build.
* `Local_Development/` is the stack entry point. Its `docker-compose.yml` builds
the application by relative path (`../CV_Site_Nuxt`) rather than duplicating any
build definition.
* The design mockups live in `Local_Development/design/`.
* This knowledge bundle lives inside the application repository it describes,
which the format allows for a bundle kept as a subdirectory of a larger
repository.
# Why
A Dockerfile is part of the application, not part of the environment that runs
it. Keeping it with the app means the image definition is versioned, reviewed and
released with the code it builds, and the compose file stays a thin description
of how the pieces are wired together for local work.
# Consequences
* The compose file cannot be built from a checkout of `Local_Development/` alone;
it needs the sibling application repository present.
* Adding a service means adding a compose entry that points at another
repository's Dockerfile.
# State
The compose file is being written and is not yet valid: the build key is
malformed and the port entry is empty. The shape of the mount it will use is still
an [open question](/open-questions.md).
+16
View File
@@ -0,0 +1,16 @@
---
okf_version: "0.2"
---
# Start here
* [Open questions](open-questions.md) - What is still undecided for the Nuxt site.
* [Update log](log.md) - History of changes to this bundle.
# Decisions
* [Dev container shape](decisions/dev-container-shape.md) - The source is bind-mounted into a container that already holds the dependencies, and the dev server runs as the image's `node` user.
* [Build layer order](decisions/build-layer-order.md) - Why the manifests are copied before the source, and what invalidates what.
* [Build context filter](decisions/build-context-filter.md) - What `.dockerignore` may exclude, and the one thing it must never exclude.
* [Repository and compose layout](decisions/repo-and-compose-layout.md) - The Dockerfiles live with the app; the stack is assembled in `Local_Development`.
* [Mockup layout](decisions/mockup-layout.md) - One `DESIGN.md` per screen, with the screenshot and the source embedded.
+8
View File
@@ -0,0 +1,8 @@
# Update Log
## 2026-10-18
* **Creation**: Established the Nuxt bundle [index](/index.md) and the [decisions](/decisions/index.md) index.
* **Decision**: Recorded the [dev container shape](/decisions/dev-container-shape.md) — source bind-mounted, dependencies in the image, run as the image's `node` user.
* **Decision**: Recorded [build layer order](/decisions/build-layer-order.md) and the [build context filter](/decisions/build-context-filter.md), including the measured failure when a `COPY` target is excluded.
* **Decision**: Recorded the [repository and compose layout](/decisions/repo-and-compose-layout.md) and the [mockup layout](/decisions/mockup-layout.md).
* **Creation**: Added [open questions](/open-questions.md), including the shape of the production image.
+38
View File
@@ -0,0 +1,38 @@
---
type: Open Questions
title: Open questions
description: Decisions still to make for the Nuxt site, with what needs each answer.
tags: [decision, open]
status: draft
generated: { by: opencode/deepseek-v4.1-flash, at: 2026-10-18T12:41:52Z }
---
| Question | Needed by | Default if nobody decides |
|---|---|---|
| Shape of the production image: a runnable Node server, or static `.output/public/` files for the gateway to embed | the next Dockerfile step | None. The empty `Dockerfile` stays empty. |
| How the compose service mounts the source: the whole repository plus a volume for `node_modules`, or only the directories that get edited | finishing `Local_Development/docker-compose.yml` | None. The compose file is not yet valid. |
| Which pnpm version the production image pins | writing the production image | The same as dev, 11.26.0. |
| Whether these decisions stay in this bundle or fold into the sibling `OKF_CV_Website` bundle, which already describes the frontend at design level | after the production image exists | None. |
# The mount trade-off, in detail
Measured on the whole-repository mount:
* An anonymous volume is created once. After a dependency change the stale
contents persist unless the volume is renewed, and the renewal command has not
been tested.
* Docker creates an empty, root-owned `node_modules` directory in the repository
on the first run, unless that directory already exists.
The alternative — mounting only the directories that get edited — removes the
volume, the renewal step and the root-owned directory entirely, and keeps `.nuxt`
inside the container rather than in the working tree. It costs one compose line
per top-level directory, so a new directory silently fails to appear in the
container until the compose file is updated.
# Related
The Nuxt frontend is described at design level in `OKF_CV_Website`, in
`architecture/frontend.md` and `decisions/static-nuxt-in-gateway.md`. Those
documents state that the site is generated to static files and embedded in the
gateway image, which is an input to the production-image question above.