Skip to content

docs(web/guides): add Installing with CommandBox guide for Wheels 4#3185

Closed
wheels-bot[bot] wants to merge 1 commit into
developfrom
docs/bot-3183-docs-add-an-installing-with-commandbox-support-tie
Closed

docs(web/guides): add Installing with CommandBox guide for Wheels 4#3185
wheels-bot[bot] wants to merge 1 commit into
developfrom
docs/bot-3183-docs-add-an-installing-with-commandbox-support-tie

Conversation

@wheels-bot

@wheels-bot wheels-bot Bot commented Jun 12, 2026

Copy link
Copy Markdown
Contributor

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|) before box server start can boot, the server
management workflow via CommandBox, and the explicit boundary between what CommandBox
provides and what requires the standalone wheels binary. A 2.x/3.x → 4.0 command
mapping 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.

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>

@wheels-bot wheels-bot Bot left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

  1. The placeholder list is incomplete: config/app.cfm also ships |appName| (lines 57–87). Steps 2–3 cover server.json and config/settings.cfm, but the published zip contains a third placeholder: tools/build/base/config/app.cfm line 10 is this.name = "|appName|";, and tools/build/scripts/prepare-base.sh line 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| in config/app.cfm as well.

  2. 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.rewrites pointing at public/urlrewrite.xml, app.cfengine, app.libDirs — but the example shows flat top-level cfengine/webroot keys and omits rewrites and libDirs entirely. 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 the app/lib directory. Fix: show the actual template content with the two tokens substituted — same nested shape as examples/starter-app/server.json, keeping the web.rewrites block and app.libDirs.

  3. There is no default port 8080 (lines 95 and 97; also the example reload URL on line 124). The template server.json sets no web.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.md line 75). The hedge "the port shown in the CommandBox output" is correct; "(default 8080)" is not, and step 6 telling readers to open http://localhost:8080 sends most of them to a dead URL. Fix: drop the default-8080 claim, point readers at the port from box server info (or the browser CommandBox opens automatically), and either mark the line-124 URL port as illustrative or recommend pinning web.http.port in server.json so 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 for wheels-base-template, wheels-core, wheels-cli, wheels-starter-app).
  • The wheels-cli deprecation wording ("does not know 4.0+", removal in v5) matches v4-0-0/upgrading/3x-to-4x.mdx lines 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 in cfml-engines.mdx.
  • Frontmatter type: howto matches installing.mdx; sidebar.order: 7 is unique in start-here/.
  • Changelog fragment changelog.d/3183-commandbox-install-guide.added.md follows the fragment convention (no direct CHANGELOG.md edit).

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).

@bpamiri

bpamiri commented Jun 13, 2026

Copy link
Copy Markdown
Collaborator

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.

@bpamiri bpamiri closed this Jun 13, 2026
@bpamiri bpamiri deleted the docs/bot-3183-docs-add-an-installing-with-commandbox-support-tie branch June 13, 2026 04:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: add an "Installing with CommandBox" support-tier page to the v4 guides — ForgeBox packages are published but completely undocumented

1 participant