Fast Docker build: cache mounts, layer ordering, multi-stage nvim

[IlyaasK]

Fast Docker build: cache mounts, layer ordering, multi-stage Neovim (+1 bug fix)

Applies the principles from eblog's FastDocker to puffertank.dockerfile.

Changes

Cache mounts (BuildKit) — --mount=type=cache so rebuilds reuse state across builds:

• /root/.cache/uv → the ~3GB of cu130 torch wheels download once, not on every layer invalidation
• /root/.cache/puffer → experiments.zip baseline download survives rebuilds
• /var/cache/apt + /var/lib/apt → package lists/debs shared across builds
• /root/.ccache (was already present)

Layer ordering: least → most frequently changed

• COPY init.vim (was line 29) and COPY entrypoint.sh (was line 59) moved to the end. Previously, editing your vimrc invalidated the nsight, torch, and pufferlib layers — a multi-GB re-download per config tweak. Now a vimrc edit rebuilds only the final ~0s COPY layer.
• ARG NEOVIM_REF / PUFFERLIB_REF / PUFFERAI_REF let you refresh git-clone layers with --build-arg instead of editing the file (Docker caches git clone layers forever since it never re-checks the remote). Defaults unchanged: master / 4.0 / 4.0.

Multi-stage build (ship the pizza, not the oven)

• Neovim now builds in a nvim-builder stage with CMAKE_INSTALL_PREFIX=/opt/nvim; the final image copies only the installed runtime. Drops the nvim source tree + build artifacts (~1GB) and cmake/ninja/gettext/unzip from the final image.
• make -j$(nproc) parallelizes the compile.

Smaller, granular layers

• Two scattered apt-get install RUNs merged into one update && install layer (same package list); nsight stays on its own layer since it's large and version-bumped independently.
• COPY --chmod=755 replaces the COPY+chmod pair.
• Removed the trailing RUN apt-get clean — a cleanup in a new layer never shrinks the layers below it.

.dockerignore — rewritten as a whitelist: build context drops from the whole repo to 2 files (274 bytes measured with buildx --check), and the broken puffertank -> /puffertank symlink can no longer break context transfer.

Bug fix (separate commit)

Line 65 ends with \␣ (backslash + trailing space). The backslash escapes the space, so the shell sees an unescaped newline: a syntax error at && echo …. Every bashrc line from alias vim onward — the vim/diff/pip aliases, venv activation, cd pufferlib, the mesa env var — silently never applied in any image built from this revision. Continuations normalized; all 7 payloads byte-identical.

Validation

• docker buildx build --check -f puffertank.dockerfile . → passes, no warnings (full frontend parse; base image not pulled).
• The bashrc RUN body and the nested-quote alias diff line both execute cleanly under sh (the original fails with sh: syntax error near unexpected token '&&').

Not yet measured

Wall-clock build/rebuild timings are intentionally left out: this was prepared on an arm64 box without a GPU (no cu130 aarch64 torch wheels exist), so a fair measurement must happen on an amd64 + GPU machine. Expected effects once measured there:

• cold build: nvim ~4x faster compile (-j), everything else roughly unchanged
• warm rebuild after a config edit: was full nsight+torch+pufferlib re-download; now a sub-second COPY
• image size: minus nvim source/build tree and cmake/ninja/gettext/unzip