docs(docs): add wheels deploy guides and CLI reference (starlight-native mdx)#2190
Merged
Conversation
…ive mdx) Adds the deployment docs slot deliberately left empty when the v4 guides rewrite shipped (#2169). The wheels deploy Kamal port (#2187) is now documented for end users: Deployment guides (web/sites/guides/src/content/docs/v4-0-0-snapshot/deployment/): - index.mdx rewrite: replaces the "no wheels deploy in 4.0" placeholder with a proper landing describing the Kamal lineage, when to use it, and the zero-downtime rollover story - first-deploy.mdx: guided tutorial from init → setup → deploy - config-reference.mdx: full deploy.yml schema, with every allowed top-level key sourced from Validator.cfc - accessories.mdx: sidecar lifecycle - secrets.mdx: .kamal/secrets and the 5 adapters (op/bw/aws/lpass/doppler) - hooks.mdx: KAMAL_* env contract + pre/post/post-failure - migrating-from-kamal.mdx: coexistence contract, ERB→Mustache divergence CLI reference (web/sites/guides/src/content/docs/v4-0-0-snapshot/command-line-tools/commands/deploy/): - 69 per-verb pages — every verb in DeployMainCli, DeployAppCli, DeployProxyCli, DeployAccessoryCli, DeployBuildCli, DeployRegistryCli, DeployServerCli, DeployPruneCli, DeployLockCli, DeploySecretsCli - Each page: frontmatter, synopsis, flags table, behavior, examples - Behavior sourced directly from the *Cli.cfc files on develop Sidebar wiring (web/sites/guides/src/sidebars/v4-0-0-snapshot.json): - Deployment & Operations: 6 new items promoted to top, existing production-config/docker/vm/security/observability retained below - CLI Reference: new "Deploy Commands" subsection with collapsible per-verb-group leaves Build: pnpm --filter @wheels-dev/site-guides build succeeds, 415 pages. Cross-reference: #2187 (the port).
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
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
Fills the deployment docs slot deliberately left empty when the v4 guides rewrite shipped (#2169). The Kamal-based
wheels deployport (#2187) is now documented for end users in Starlight-native MDX underweb/sites/guides/src/content/docs/v4-0-0-snapshot/.Deployment guides (7 files under
deployment/):index.mdxrewrite — replaces the "no wheels deploy in 4.0 today" placeholder with a landing page covering the Kamal lineage, when to reach for the tool vs. alternatives, and the zero-downtime rollover story.first-deploy.mdx— guided tutorial fromwheels deploy init→wheels deploywith Starlight<Steps>.config-reference.mdx— fulldeploy.ymlschema. Every allowed top-level key was sourced directly fromcli/lucli/services/deploy/config/Validator.cfcon this branch.accessories.mdx,secrets.mdx,hooks.mdx— topic-focused how-tos.migrating-from-kamal.mdx— the ERB-vs-Mustache divergence is called out in a<Aside type="caution">at the top.CLI reference (69 files under
command-line-tools/commands/deploy/):app/proxy/accessory/build/registry/server/prune/lock/secrets). Each page carries frontmatter, synopsis, flags table, behavior paragraph, and 1-2 examples. Behavior is sourced directly from the*Cli.cfcfiles on develop — e.g. the Phase 2 marker-fileapp live/app maintenanceimplementation is documented honestly rather than as full proxy-native maintenance.Sidebar (
src/sidebars/v4-0-0-snapshot.json):production-config,docker-deployment,vm-deployment,security-hardening,observability-and-loggingentries retained below unchanged.Test plan
cd web && pnpm --filter @wheels-dev/site-guides build— green. 415 pages built; all 76 new pages render with correct sidebar position.python3 -c "import json; json.load(open(...))").start-here/tutorial/index.mdx,basics/models-and-the-orm.mdx).pnpm --filter @wheels-dev/site-guides devand click through the new sidebar sections.Notes
docs/superpowers/specs/2026-04-20-wheels-deploy-kamal-port-design.md.cli/CLAUDE.md:67the commit does not include a Co-Authored-By trailer.