mirror of
https://github.com/docker/docs.git
synced 2026-10-28 07:15:09 +03:00
83f2aa3070
## Summary The kit examples page covered tool installation and credential injection but never showed how to customize the shell environment — sourcing a tool's init script so its command lands on `PATH` in every shell. This adds a "Customize the shell environment" section, documents install-command gotchas that apply to any download-based kit, and fixes a Vale rule that tripped on product names ending in `!`. Two commits: 1. **docs: add shell environment customization to kit examples** - Worked example uses **nvm** — it installs cleanly in a default sandbox (reachable egress, no extra packages), so the snippet works as copy-pasted. It appends to `/etc/sandbox-persistent.sh` — the sandbox's persistent environment file, sourced for both interactive and non-interactive shells — matching the FAQ convention for custom env vars, and cross-links it. - Install-command caveats added to the "Install a tool" section: deny-by-default egress can silently block downloads; `curl … | bash` masks those failures (exits `0`, sandbox reports success while nothing installed); install steps run under `sh`, not bash; some tools need base packages such as `zip`/`unzip`. - The first draft's sdkman snippet was dropped as the primary example because it fails silently in a default sandbox (blocked `get.sdkman.io` egress + missing `zip`/`unzip`). Those failure modes are now documented as general install-command guidance, with sdkman as the illustration. 2. **vale: exempt product names ending in '!' from Docker.Exclamation** - `Docker.Exclamation` flags any word followed by `!` in bare prose, tripping on product names like SDKMAN!. Link text and code were already exempt via `IgnoredScopes`, but bare prose was not. Added an `exceptions` list (matched against the word before the `!`) so genuine exclamations are still caught. ## Learnings - `/etc/sandbox-persistent.sh` is the canonical persistence point for shell env in sandboxes — sourced before *every* bash invocation (interactive and non-interactive), so it reaches agents started with both `sbx run` and `sbx exec`. A `~/.bashrc` edit only covers interactive shells. - `curl … | bash` in an install command masks download failures: the pipe's exit status is bash's, and bash exits `0` on empty input, so a domain blocked by the deny-by-default egress policy still produces a "✓ Created" sandbox with nothing installed. Download-then-run (`-o file && bash file`) surfaces the failure. - Kit install commands run under `sh` (dash), not bash — bash builtins like `source` fail with `sh: source: not found` unless piped to `bash` or wrapped in `bash -c`. - nvm won't activate while `NPM_CONFIG_PREFIX` is set (the base image sets it for its system Node); `unset NPM_CONFIG_PREFIX` before sourcing `nvm.sh`. - Vale's `exceptions` for an `existence` rule with `nonword: true` are matched against the *word* preceding the non-word token, not the full match — so a product name ending in `!` is listed without the `!` (`SDKMAN`, not `SDKMAN!`). Go's RE2 engine also has no lookahead, so token regexes can't use `(?=…)`. Generated by Claude Code --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>