docs: document custom build cold/warm cache and layer ordering#5371
Merged
Conversation
Add Docker build performance guidance for custom sandbox images: cold build versus warm rebuild behavior, Dockerfile layer ordering for cache reuse, base image pinning, and a fast-versus-slow build-directory example. Folds the guidance into the onboard --from reference for both agent variants and a consolidated Build Performance section on the OpenClaw plugins page, and adds large-context warning remediation. Addresses remaining gaps in #4683. Signed-off-by: Miyoung Choi <miyoungc@nvidia.com>
Contributor
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Enterprise Run ID: 📒 Files selected for processing (3)
✅ Files skipped from review due to trivial changes (3)
📝 WalkthroughWalkthroughThree documentation files add guidance on Docker build performance for OpenClaw plugin onboarding and NemoClaw/NemoHermes commands: shrink build context, understand cold vs warm Docker cache, prefer cache-friendly Dockerfile ordering, pin base images, and use ChangesDocker Build Performance Documentation
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Possibly related issues
Suggested labels
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
Contributor
|
🌿 Preview your docs: https://nvidia-preview-pr-5371.docs.buildwithfern.com/nemoclaw |
Contributor
E2E Advisor RecommendationRequired E2E: None Full advisor summaryE2E Recommendation AdvisorBase: Required E2E
Optional E2E
New E2E recommendations
|
Contributor
Vitest E2E Scenario RecommendationRequired Vitest E2E scenarios: None Full Vitest E2E advisor summaryVitest E2E Scenario AdvisorBase: Required Vitest E2E scenarios
Optional Vitest E2E scenarios
Relevant changed files
|
Contributor
PR Review AdvisorFindings: 0 needs attention, 1 worth checking, 0 nice ideas Review findings🛠️ Needs attention
🔎 Worth checking
🌱 Nice ideas
Consider writing more tests for
Since last review detailsCurrent findings:
This is an automated advisory review. A human maintainer must make the final merge decision. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
docs/reference/commands.mdx (1)
344-344: 📐 Maintainability & Code Quality | ⚡ Quick winWrap file names in inline code formatting.
At Line 344 and Line 368,
Dockerfileshould be formatted as inline code to match docs formatting rules for file names.Suggested edit
-Move the Dockerfile into a smaller dedicated directory or add `.dockerignore` entries for generated artifacts to shrink the context. +Move the `Dockerfile` into a smaller dedicated directory or add `.dockerignore` entries for generated artifacts to shrink the context.-- Order Dockerfile instructions from least-changing to most-changing: base image, system packages, dependency manifests, dependency install, then application source. +- Order `Dockerfile` instructions from least-changing to most-changing: base image, system packages, dependency manifests, dependency install, then application source.As per coding guidelines, CLI commands, file paths, flags, parameter names, and file names must use inline
codeformatting.Also applies to: 368-368
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/reference/commands.mdx` at line 344, Replace the plain occurrences of Dockerfile with inline code formatting (`Dockerfile`) in the documentation; specifically update the two instances mentioned (the plain text "Dockerfile" at the referenced spots) so they use backticks, and scan nearby lines to ensure other CLI commands, file paths, flags, and file names follow the same inline `code` formatting convention.Source: Coding guidelines
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/reference/commands-nemohermes.mdx`:
- Line 286: Update the docs text in docs/reference/commands-nemohermes.mdx to
recommend pinning base images by immutable digest (sha256) rather than by tag or
release ref; reference the implementation in
src/lib/onboard/sandbox-dockerfile-patch-flow.ts which resolves and pins to a
digest and adjust the sentence “Pin the base image to an explicit tag or release
ref…” to something like “Pin the base image to an immutable digest (sha256) so
warm rebuilds resolve the same cached base.” Ensure the doc links or mentions
sandbox-dockerfile-patch-flow.ts as the source of truth for how pinning is
performed.
- Line 260: Replace the plain text file name "Dockerfile" in the sentence that
suggests moving it or adding .dockerignore entries with inline code formatting
(i.e., surround Dockerfile with backticks) so the file name follows the docs
style; update the mention of ".dockerignore" if needed to match surrounding
formatting in the same sentence within the commands-nemohermes.mdx content.
---
Nitpick comments:
In `@docs/reference/commands.mdx`:
- Line 344: Replace the plain occurrences of Dockerfile with inline code
formatting (`Dockerfile`) in the documentation; specifically update the two
instances mentioned (the plain text "Dockerfile" at the referenced spots) so
they use backticks, and scan nearby lines to ensure other CLI commands, file
paths, flags, and file names follow the same inline `code` formatting
convention.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: c5ab7779-81b3-49a7-b668-baf2c0fd6d26
📒 Files selected for processing (3)
docs/deployment/install-openclaw-plugins.mdxdocs/reference/commands-nemohermes.mdxdocs/reference/commands.mdx
| Without a `.dockerignore`, onboarding still skips common large or local-only directories (`node_modules`, `.git`, `.venv`, and `__pycache__`) while staging this context. | ||
| Other build outputs such as `dist/`, `target/`, or `build/` are included unless your `.dockerignore` excludes them. | ||
| If the staged context is larger than 100 MB, onboarding prints a warning before the Docker build starts. | ||
| Move the Dockerfile into a smaller dedicated directory or add `.dockerignore` entries for generated artifacts to shrink the context. |
Contributor
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Format Dockerfile as inline code.
This sentence follows the docs style for .dockerignore, but the file name itself is plain text. As per coding guidelines, file names must use inline code formatting.
♻️ Suggested edit
-Move the Dockerfile into a smaller dedicated directory or add `.dockerignore` entries for generated artifacts to shrink the context.
+Move the `Dockerfile` into a smaller dedicated directory or add `.dockerignore` entries for generated artifacts to shrink the context.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| Move the Dockerfile into a smaller dedicated directory or add `.dockerignore` entries for generated artifacts to shrink the context. | |
| Move the `Dockerfile` into a smaller dedicated directory or add `.dockerignore` entries for generated artifacts to shrink the context. |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/reference/commands-nemohermes.mdx` at line 260, Replace the plain text
file name "Dockerfile" in the sentence that suggests moving it or adding
.dockerignore entries with inline code formatting (i.e., surround Dockerfile
with backticks) so the file name follows the docs style; update the mention of
".dockerignore" if needed to match surrounding formatting in the same sentence
within the commands-nemohermes.mdx content.
Source: Coding guidelines
| - A warm rebuild reuses cached layers when the base image and earlier layers are unchanged, so it is much faster than the first build. | ||
| - Order Dockerfile instructions from least-changing to most-changing: base image, system packages, dependency manifests, dependency install, then application source. | ||
| This lets warm rebuilds reuse cached dependency layers instead of reinstalling on every source change. | ||
| - Pin the base image to an explicit tag or release ref so warm rebuilds resolve the same cached base instead of pulling a new one. |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Use an immutable digest for base-image pinning.
An explicit tag or release ref can move, so it does not guarantee the stable cache key this guidance is trying to describe. Based on src/lib/onboard/sandbox-dockerfile-patch-flow.ts, the implementation resolves and pins the base image to a digest before patching.
♻️ Suggested edit
-- Pin the base image to an explicit tag or release ref so warm rebuilds resolve the same cached base instead of pulling a new one.
+- Pin the base image to an immutable digest so warm rebuilds resolve the same cached base instead of pulling a new one.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| - Pin the base image to an explicit tag or release ref so warm rebuilds resolve the same cached base instead of pulling a new one. | |
| - Pin the base image to an immutable digest so warm rebuilds resolve the same cached base instead of pulling a new one. |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/reference/commands-nemohermes.mdx` at line 286, Update the docs text in
docs/reference/commands-nemohermes.mdx to recommend pinning base images by
immutable digest (sha256) rather than by tag or release ref; reference the
implementation in src/lib/onboard/sandbox-dockerfile-patch-flow.ts which
resolves and pins to a digest and adjust the sentence “Pin the base image to an
explicit tag or release ref…” to something like “Pin the base image to an
immutable digest (sha256) so warm rebuilds resolve the same cached base.” Ensure
the doc links or mentions sandbox-dockerfile-patch-flow.ts as the source of
truth for how pinning is performed.
miyoungc
added
area: docs
cv
approved these changes
Jun 13, 2026
Release-pinned sandbox base image refs are not fully published yet (tracked in #4052), so recommend pinning by explicit tag or digest to avoid implying an unsupported release-ref mechanism. Signed-off-by: Miyoung Choi <miyoungc@nvidia.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds the remaining Docker build performance guidance for custom sandbox images identified in #4683: the cold-build versus warm-rebuild distinction and Dockerfile layer ordering for cache reuse. These were the two gaps not yet covered on
mainafter the.dockerignoresupport docs landed.Related Issue
Addresses #4683 (remaining gaps; issue stays open if maintainers want further consolidation).
Changes
docs/deployment/install-openclaw-plugins.mdxcovering cold vs warm builds, layer ordering, base image pinning, and a practical fast-vs-slow build-directory example.--from <Dockerfile>reference indocs/reference/commands.mdxanddocs/reference/commands-nemohermes.mdx, with a pointer to the Onboard Profiling Traces section for diagnosis.Type of Change
Verification
npx prek run --all-filespassesnpm testpassesnpm run docsbuilds without warnings (doc changes only)Signed-off-by: Miyoung Choi miyoungc@nvidia.com
Summary by CodeRabbit