docs(docker): keep managed Node visible with BuildKit cache mounts

[MHJahanbakhsh]

Summary

• Fixes #880: BuildKit cache mounts targeting /pnpm/store hide Node installed via pnpm runtime set … -g, because the managed runtime lives under that store.
• Recipes now mount the cache at /var/cache/pnpm and pass --store-dir /var/cache/pnpm, so the default store (and node on PATH) stay available during pnpm install.
• Adds a warning callout explaining why /pnpm/store must not be used as the cache mount target when using the managed runtime.

Test plan

• Confirm the warning renders correctly on the Docker docs page
• Spot-check Example 1 and Example 2 Dockerfiles for valid BuildKit syntax
• Optionally reproduce Docker recipe hides the managed Node runtime behind the /pnpm/store cache mount #880 with the old recipe, then verify the updated recipe keeps node --version working inside a cache-mounted RUN

[bolt-new-by-stackblitz]

Run & review this pull request in StackBlitz Codeflow.

[vercel]

@MHJahanbakhsh is attempting to deploy a commit to the pnpm Team on Vercel.

A member of the Team first needs to authorize it.

[qodo-code-review]

Qodo reviews are paused for this user.

Troubleshooting steps vary by plan Learn more →

On a Teams plan?
Reviews resume once this user has a paid seat and their Git account is linked in Qodo.
Link Git account →

Using GitHub Enterprise Server, GitLab Self-Managed, or Bitbucket Data Center?
These require an Enterprise plan - Contact us
Contact us →

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: d1680954-743f-45b3-83c9-ad8af9a839cc

📥 Commits

Reviewing files that changed from the base of the PR and between 364ae5d and b430255.

📒 Files selected for processing (1)

• docs/docker.md

Included review availability: Your plan includes up to 2 reviews per rolling hour; 1 remains after this review.

📜 Recent review details

⏰ Context from checks skipped due to timeout. (1)

• GitHub Check: Greptile Review

⚠️ CI failures not shown inline (1)

Commit Status: Vercel: Vercel

Conclusion: failure

Authorization required to deploy.

🧰 Additional context used

🧠 Learnings (3)

📚 Learning: 2026-07-31T10:43:55.031Z

Learnt from: zkochan
Repo: pnpm/pnpm.io PR: 849
File: blog/releases/11.15-11.19.md:74-74
Timestamp: 2026-07-31T10:43:55.031Z
Learning: When documenting pnpm peer dependency resolution, accurately explain that pnpm can treat a package listed only in peerDependenciesMeta as an optional peer, even without a matching peerDependencies entry. Verify examples such as debug and distinguish this behavior from the conventional peerDependencies-plus-peerDependenciesMeta declaration.

Applied to files:

• docs/docker.md

📚 Learning: 2026-08-10T14:27:38.429Z

Learnt from: zkochan
Repo: pnpm/pnpm.io PR: 866
File: blog/2026-08-10-whats-different-in-pnpm-12.md:27-32
Timestamp: 2026-08-10T14:27:38.429Z
Learning: In the pnpm.io repository, do not report missing language identifiers on Markdown fenced code blocks in docs/**/*.md or blog/**/*.md as MD040-style issues when the repository has no Markdown lint configuration or lint script. Only flag such omissions if Markdown linting is explicitly adopted or the changed file establishes a conflicting local convention.

Applied to files:

• docs/docker.md

📚 Learning: 2026-08-15T18:14:48.091Z

Learnt from: zkochan
Repo: pnpm/pnpm.io PR: 882
File: docs/cli/shim.md:0-0
Timestamp: 2026-08-15T18:14:48.091Z
Learning: In pnpm documentation, treat `docs/global-packages.md#trust` as the canonical definition of the four project-aware global-bin trust policies. Documentation that links to this section should avoid duplicating those policy definitions unless additional local context is necessary.

Applied to files:

• docs/docker.md

🔇 Additional comments (3)

docs/docker.md (3)

83-93: LGTM!

---

116-121: LGTM!

---

186-187: LGTM!

---

📝 Walkthrough

Walkthrough

The Docker documentation warns that mounting a cache over /pnpm/store can hide a globally managed Node.js runtime. Both examples now use /var/cache/pnpm for the cache mount and pnpm store directory.

Changes

Docker cache mount guidance

Layer / File(s)	Summary
Separate cache mount from managed runtime docs/docker.md	The guide documents the /pnpm/store default, warns about globally managed Node.js, and updates both Docker examples to use /var/cache/pnpm for dependency caching.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Merge Risk: ⚪ Minimal · up to b4302

This is a localized Docker documentation change with no actionable merge-blocking risk remaining after normal checks and review.

Suggested reviewers: zkochan

Poem

A rabbit hops where cache paths gleam,
Keeping Node awake inside the stream.
/var/cache/pnpm now marks the way,
While /pnpm/store stays safe each day.
Docker builds can run and play.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The documentation changes address issue #880 by moving the cache mount and store directory away from the managed Node runtime.
Out of Scope Changes check	✅ Passed	The changes are limited to Docker documentation and directly support the linked issue objectives.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the Docker documentation change that keeps the managed Node runtime visible with BuildKit cache mounts.

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge; the revised examples preserve the managed Node runtime while retaining pnpm package caching.

The cache target and explicit store directory are aligned in every changed install command, and the documented workaround addresses the store-overlay failure without introducing a supported-path regression.

_{Reviews (1): Last reviewed commit: "docs(docker): keep managed Node visible ..." | Re-trigger Greptile}