mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-17 04:21:24 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Each merge to master builds the production Docker image for amd64 and arm64 and pushes it to GHCR > - Each build pushes three layers again, about 3.5 GB compressed of a 4.7 GB image > - A file-by-file comparison of two consecutive master images shows that about 95% of those bytes do not change between commits > - The unchanged bytes are in the same layers as small files that change on every commit, so the registry sees new layers > - This pull request moves the unchanged bytes into their own layers > - The benefit is a smaller push for each master build and a smaller pull for each deploy ## Linked Issues or Issue Description **What existing behavior does this improve?** The production image build. It pushes about 3.5 GB of layers for each architecture on each master commit. Each deploy pulls the same bytes again. **Subsystem affected** Docker image build (`Dockerfile`, `production` and `runner-provider-pack` stages). **Current behavior** I compared the amd64 images of two consecutive master commits (`2174f2d` and `dfc510b`, 15 changed server source files). I hashed each file in the three layers that changed. | Layer | Compressed | Content that is identical between the two builds | | --- | --- | --- | | `COPY --from=build /app /app` | 1,404 MB | 97.5%. The root `node_modules` is 2.86 GB of 4.13 GB and has 0 changed files. | | `COPY /provider-pack` | 1,008 MB | 100% of the 112 files of 1 MiB or more (2.54 GB). Only 32 small files change (manifest, `.modules.yaml`, `.bin` shims). | | `COPY /provider-pack-transport/` | 1,059 MB | The archives differ only in tar timestamps. This pull request does not change this layer. | **Proposed behavior** - Copy the root `node_modules` from the `deps` stage as its own layer. Copy the remainder of `/app` from the `build` stage with `--exclude=node_modules`. - In the `runner-provider-pack` stage, move pack files of 1 MiB or more to `/provider-pack-large` after the transport archive is made. Set their mtimes to a fixed value. - Copy `/provider-pack-large` with `COPY --link`, then copy the small remainder of the pack to the same directory. **Reason and benefit** The dependency layer changes only when the lockfile changes. The large provider-pack layer changes only when a provider version changes. The expected push for a commit that changes source only goes from about 3.5 GB to about 1.5 GB for each architecture. The master build runs about 140 times a day on AWS runners, and this traffic is about 570 GB a day of billed data transfer. Deploy pulls become smaller by the same amount. **Breaking changes** None. The file tree of the image is the same. Provider-pack files of 1 MiB or more now have an mtime of 1970-01-01. ## What Changed - `Dockerfile`: the `production` stage copies `/app/node_modules` from `deps` first, then `/app` from `build` without the root `node_modules`. - `Dockerfile`: the `runner-provider-pack` stage splits large pack files into `/provider-pack-large` with fixed mtimes. The `production` stage copies that tree with `--link` before the remainder of the pack. - `server/src/__tests__/docker-image-layer-reuse.test.ts`: a drift guard for the copy order, the exclude, the `--link`, and the position of the split after the archive step. ## Verification - `cd server && npx vitest run src/__tests__/docker-image-layer-reuse.test.ts src/__tests__/docker-build-stamp.test.ts`: 9 tests pass. The 2 new tests fail against the `Dockerfile` on master. - `node scripts/check-docker-deps-stage.mjs`: PASS. - `pnpm verify`: exit 2 (the `Dockerfile` is a global CI input). Required CI supplies the broad coverage. - A small Dockerfile with the same syntax version (`docker/dockerfile:1.20`) and the same four `COPY` instructions, built two times with a changed stamp file: - `--exclude=node_modules` leaves out only the root `node_modules`. A nested `node_modules` stays. - The dependency layer has the same digest in the two builds. - The large-file layer has the same digest in the two builds only with `--link` and fixed mtimes. Without one of them the digest changes. - Hard links between large files stay hard links. The merged directory contains each file one time. - Evidence that the `build` stage writes nothing to the root `node_modules`: in the published image, all 107,413 files there have an mtime in the minute of the `deps` install. The app build ran 15 hours later. **Not verified:** a full build of the production image with this `Dockerfile`. The local Docker disk was full, and no pre-merge workflow builds this image. The first full build is the master build after merge. The check after merge is to compare the layer digests of two consecutive master images. ## Risks - Medium until the first master build. If the image build fails, master image builds stop until a revert. No broken image can be published, because the build fails before the push. - If a future build step writes to the root `node_modules` in the `build` stage, the image will not contain that change. The comment in the `Dockerfile` states this rule. - A file that crosses the 1 MiB boundary moves between the two pack layers. This only changes which layer is pushed. - The first build after merge pushes all the new layers one time. ## Model Used - Claude Fable 5.2 (`claude-fable-5-2`), Anthropic, in Claude Code with tool use (shell, AWS CLI, Docker, registry API). ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [ ] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>