[andrew]

Add a Docker build guide with npm and Bundler examples, persistent proxy storage, local and CI networking, and BuildKit registry mirrors for base images. Explain how the shared package cache works alongside layer caches and cache mounts, including the pull-only OCI endpoint's limitation for registry-cache exports.

Link the guide from the README's quick start.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.

[simonchrz]

Checked the guide against main: flags, /npm/ and /gem/ paths, proxy_cache_hits_total, audit passthrough, the docker.io mirror via ns, and the pull-only OCI note all match. The example command also works from an empty directory since the database and storage directories are created on startup.

A few small optional points:

1. Bundler only falls back to the original source when mirror.https://rubygems.org.fallback_timeout is set. Without it, bundle install fails if the proxy is unreachable. Might be worth naming the setting in that sentence.
2. If --build-arg PROXY_URL is forgotten, npm gets --registry=/npm/ and fails with an unclear error. "${PROXY_URL:?PROXY_URL build arg required}" in the RUN lines would make that obvious.
3. The Bundler mirror setting isn't kept in the image, but the proxy URL still shows up in docker history because RUN lines are recorded with build args. Only matters if the URL contains credentials.
4. npm ci --no-audit --no-fund would avoid the upstream audit requests mentioned in the npm section.