docs(web/guides): add Installing with CommandBox guide for Wheels 4#3185
docs(web/guides): add Installing with CommandBox guide for Wheels 4#3185wheels-bot[bot] wants to merge 1 commit into
Conversation
Documents the four ForgeBox packages, post-install placeholder edits, the server management workflow via box server start, and the boundary between CommandBox and the standalone wheels CLI. Cross-links added from installing.mdx and cfml-engines.mdx. Closes #3183. Signed-off-by: wheels-bot[bot] <wheels-bot[bot]@users.noreply.github.com> Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
There was a problem hiding this comment.
Wheels Bot — Reviewer
TL;DR: This PR adds the "Installing with CommandBox" guide requested in #3183, and the structure, cross-links, changelog fragment, and commit message are all in good shape — but the install walkthrough has three factual errors verified against the actual build sources, so the verdict is request changes. (Submitted as a comment-state review because GitHub forbids a request-changes review on the bot's own PR — treat it as blocking.) The placeholder-edit steps miss a third shipped file (config/app.cfm), the "minimal edited server.json" example does not match the file the template actually ships (and drops the URL-rewrite config), and the claimed default port 8080 does not exist — the template sets no port, so CommandBox assigns a random one.
All findings are in web/sites/guides/src/content/docs/v4-0-0/start-here/installing-with-commandbox.mdx; line numbers refer to that file. (Findings are body-anchored — inline comment attachment was not available in this session.)
Correctness
-
The placeholder list is incomplete:
config/app.cfmalso ships|appName|(lines 57–87). Steps 2–3 coverserver.jsonandconfig/settings.cfm, but the published zip contains a third placeholder:tools/build/base/config/app.cfmline 10 isthis.name = "|appName|";, andtools/build/scripts/prepare-base.shline 63 copies that file verbatim into the build — the build-time substitution pass (prepare-base.sh lines 70–74) only replaces@build.version@-style tokens, not pipe-delimited tokens. A reader following the page as written boots an app whose CFML application name is the literal string|appName|, and any two apps installed this way on the same engine would share an application scope. The page promises "the manual edits the installer leaves to you" (line 16), so add a step (or a row in step 2 covering both files): replace|appName|inconfig/app.cfmas well. -
The "minimal edited
server.json" example contradicts the file the user is editing (lines 68–76). The shipped template (tools/build/base/server.json) is nested —web.host,web.webroot,web.rewritespointing atpublic/urlrewrite.xml,app.cfengine,app.libDirs— but the example shows flat top-levelcfengine/webrootkeys and omitsrewritesandlibDirsentirely. Step 2 tells the reader to replace two tokens in place, so the edited file keeps the nested shape; a reader who pastes the example instead silently loses URL rewriting (Wheels extensionless routes) and theapp/libdirectory. Fix: show the actual template content with the two tokens substituted — same nested shape asexamples/starter-app/server.json, keeping theweb.rewritesblock andapp.libDirs. -
There is no default port
8080(lines 95 and 97; also the example reload URL on line 124). The templateserver.jsonsets noweb.http.port, and CommandBox assigns a random available port when none is configured — the repo docs say so for this exact template: "…and started a Lucee server on a random port" (web/sites/guides/src/content/docs/v3-0-0/index.mdline 75). The hedge "the port shown in the CommandBox output" is correct; "(default8080)" is not, and step 6 telling readers to openhttp://localhost:8080sends most of them to a dead URL. Fix: drop the default-8080 claim, point readers at the port frombox server info(or the browser CommandBox opens automatically), and either mark the line-124 URL port as illustrative or recommend pinningweb.http.portinserver.jsonso the URLs in the rest of the page hold.
Docs
Everything else verifies cleanly against the repo, for the record:
- The four ForgeBox slugs and per-release publishing match
.github/workflows/release.yml(artifacts forwheels-base-template,wheels-core,wheels-cli,wheels-starter-app). - The
wheels-clideprecation wording ("does not know 4.0+", removal in v5) matchesv4-0-0/upgrading/3x-to-4x.mdxlines 396–400. - All link targets exist (
installing.mdx,cfml-engines.mdx,upgrading/3x-to-4x.mdx); the relative../installing-with-commandbox/LinkCard href matches the sibling style incfml-engines.mdx. - Frontmatter
type: howtomatchesinstalling.mdx;sidebar.order: 7is unique instart-here/. - Changelog fragment
changelog.d/3183-commandbox-install-guide.added.mdfollows the fragment convention (no directCHANGELOG.mdedit).
Commits
Single commit docs(web/guides): add Installing with CommandBox guide for Wheels 4 conforms to commitlint.config.js (valid type, header under 100 chars).
|
Superseded by #3198 (merged): a propose-fix draft that raced the ForgeBox path-repair campaign for the same issue; the campaign PR landed first and closed the underlying issue. Closing the duplicate. |
This PR adds a new "Installing with CommandBox" page to the v4 guides at
web/sites/guides/src/content/docs/v4-0-0/start-here/installing-with-commandbox.mdx.The page documents the four ForgeBox packages Wheels 4 publishes on every stable
release (
wheels-base-template,wheels-core,wheels-cli,wheels-starter-app),the required post-install edits to template placeholders (
|appName|,|cfmlEngine|,|datasourceName|,|reloadPassword|) beforebox server startcan boot, the servermanagement workflow via CommandBox, and the explicit boundary between what CommandBox
provides and what requires the standalone
wheelsbinary. A 2.x/3.x → 4.0 commandmapping table covers the migration path for teams upgrading from the old CommandBox CLI
workflow.
Cross-links are added from
installing.mdx(new Aside noting the CommandBox option)and
cfml-engines.mdx(new LinkCard in the Related section).Fixes #3183.
Screenshots needed
None — this guide is text and code-fence only, no UI screenshots required.