docs: correct deploy.yml interpolation syntax and compress launch schedule#2430
Merged
docs: correct deploy.yml interpolation syntax and compress launch schedule#2430
Conversation
…edule
Campaign comms and the v4 deployment guides claimed deploy.yml uses
Mustache ({{env.X}}) when ERB is removed. Reality: ConfigLoader only
interpolates ${VAR} env-var tokens (regex \$\{([A-Z_][A-Z0-9_]*)\}) —
the same syntax Kamal supports natively. Mustache (jmustache) is used
only by `wheels deploy init` to render scaffold templates; it is not
applied to deploy.yml at runtime. A user who wrote service: {{env.APP_NAME}}
following the migration guide would have seen that string passed
literally to docker run.
Fixes the doc-drift cascade across:
- docs/releases/blog-skeletons/09-wheels-deploy.md (divergence section,
JAR count)
- docs/releases/blog-skeletons/social-announcements.md (Post 4 across
Slack, LinkedIn, X reply 2, GitHub Discussions)
- web/sites/guides/.../deployment/{migrating-from-kamal,config-reference,
architecture,index}.mdx
- CLAUDE.md (deploy critical-gotchas + stray "Ruby Kamal 2.8.2"
reference; deploy code targets and version-prints 2.4.0)
- cli/lucli/services/deploy/config/ConfigLoader.cfc (upstream docstring
that seeded the cascade)
Compresses remaining launch schedule (Posts 4-10) from every-2-days to
daily cadence; resumes 2026-05-06, lands GA on 2026-05-12. Updates
publishedAt frontmatter on Blog 09 to match.
ConfigLoader.cfc edit is comment-only — no functional changes.
4 tasks
bpamiri
added a commit
that referenced
this pull request
May 6, 2026
…2434) * docs: fix Social 4 verb count and resolve-chain claim Two follow-ups from a fact-check pass on Social 4 (post #2430): 1. Slack post claimed "Full Kamal subcommand surface (~25 verbs)" — actual is 57 distinct command paths (9 top-level + 48 across 9 sub-command groups). The original count appeared to conflate top-level verbs with sub-command groups and undercount roughly 2x. Replaced with "50+ commands across 9 sub-command groups" plus an explicit list of the top-level rollback/audit/details verbs the original line implied were sub-command groups. 2. GitHub Discussions post claimed `${VAR}` interpolation chain begins with "CLI overrides", but no production CLI passes envOverride to ConfigLoader — every Deploy*Cli.cfc instantiates `new ConfigLoader()` with no args, so envOverride is always empty in production. The parameter exists for test injection only. Replaced with the truer 3-step user-observable chain: ".kamal/secrets → process environment variables → empty string". Matches what someone reading ConfigLoader.$resolveVar will actually see. Also fixes the stale ConfigLoader.cfc line-7 pipeline comment that listed "envOverride → System.getenv → \"\"" — it omitted .kamal/secrets, contradicting the line-13 comment in the same docstring that has the correct 4-step chain. Now matches. No code changes — the .cfc edit is a one-line comment. * docs: publish Blog 09 — Porting Kamal to CFML Adds the launch-day blog post (Social 4 companion) to web/content/blog/posts/. Authored via the blog admin tool at localhost:8080; PostExporter wrote the file atomically. Merging this PR triggers web-deploy.yml (paths watcher on web/**), which runs the Astro build for site-blog and deploys to Cloudflare Pages — no manual `pnpm build` needed. Frontmatter: title, slug=wheels-deploy-kamal-port, publishedAt=2026-05-06, tags=[deployment, wheels-4, kamal], hand-tuned excerpt. Body matches the skeleton at docs/releases/blog-skeletons/09-wheels-deploy.md verbatim (135 lines, all 24 em-dashes preserved as proper UTF-8 — the EasyMDE-paste mojibake on initial save was repaired by rewriting the DB body and re-running the export through /jobs/runScheduledPublish). Companion social text for Slack/LinkedIn/X/Discussions is in docs/releases/blog-skeletons/social-announcements.md (Post 4) and ships unchanged via this same PR. * docs: quote Blog 09 frontmatter title to fix Astro YAML parse The post title contains a colon ("Porting Kamal to CFML: How wheels deploy..."), and YAML treats `title: A: B` as a nested mapping. Astro build failed with "bad indentation of a mapping entry" at line 1 col 28 (the second colon). The skeleton at docs/releases/blog-skeletons/ 09-wheels-deploy.md had this correctly quoted; the blog admin tool's YamlFrontmatter serializer dropped the quotes during export. Quoting the title alone is enough — js-yaml now parses the frontmatter correctly, all other fields round-tripped cleanly (publishedAt is already quoted, excerpt uses folded-scalar `>-` syntax, etc.). Follow-up bug to file in wheels-dev/blog: YamlFrontmatter.serialize should always quote string values that contain `: ` (or the broader set of YAML reserved characters), not just publishedAt/updatedAt timestamps. * docs: update blog visual baseline for Blog 09 entry Blog 09 ("Porting Kamal to CFML") now appears as the most-recent post on the blog index — 48,980 pixels differ vs the previous baseline, which dates from 2026-04-26 (before this post existed). Verified the diff is solely the new post entry: top-of-index now shows "Porting Kamal to CFML: How wheels deploy Ships 4.0 Apps Without Ruby" with author, May 6 2026 date, hand-tuned excerpt, and tags (#deployment, #wheels-4, #kamal). The previously-most-recent post ("Why We Rebuilt Our CI Pipeline") shifted to second place. No other layout, sidebar, or theme changes — landing/guides/api/packages/sentry baselines all matched within threshold. Baseline image taken from the visual-regression-diffs artifact of the prior failed run (job 74642066575) — i.e. the actual PNG that CI rendered, not a re-shot local copy.
3 tasks
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
1 participant
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
Two coordinated fixes uncovered while validating Blog 09 (
wheels deploy) and Social Post 4 for accuracy before publication today.1. Correct
deploy.ymlinterpolation syntax across the doc cascadeThe campaign artifacts and the v4 deployment guides described the ERB divergence as if
{{env.X}}Mustache was thedeploy.ymlreplacement. Reality:ConfigLoader.$interpolateonly handles${UPPER_SNAKE}env-var tokens (regex\$\{([A-Z_][A-Z0-9_]*)\}) — the same syntax Kamal supports natively. Mustache (jmustache) is invoked only bywheels deploy initto render scaffold templates (deploy.yml.mustache,secrets.mustache); it is not applied todeploy.ymlat runtime.A user following the original migration guide who wrote
service: {{env.APP_NAME}}would have seen that string passed literally todocker run.The truer story:
wheels deployis more schema-compatible with Kamal than the "we replaced X with Y" framing suggested. There is no new syntax to learn — the single change is a removal: ERB out, everything else identical.Affected files:
docs/releases/blog-skeletons/09-wheels-deploy.md— "The one divergence" section + JAR-count claimdocs/releases/blog-skeletons/social-announcements.md— Post 4 across Slack, LinkedIn, X reply 2, GitHub Discussionsweb/sites/guides/.../deployment/migrating-from-kamal.mdx— full ERB → ${VAR} conversion table + paragraphweb/sites/guides/.../deployment/config-reference.mdx— Variable interpolation section + No-ERB Asideweb/sites/guides/.../deployment/architecture.mdx— divergence section, frontmatter description, JAR description, added clarifying Asideweb/sites/guides/.../deployment/index.mdx— landing-page one-line divergence claimCLAUDE.md— deploy critical-gotcha New master #1; also corrects stray "Ruby Kamal 2.8.2" reference (deploy code targets and version-prints 2.4.0)cli/lucli/services/deploy/config/ConfigLoader.cfc— fixes the upstream docstring that seeded the cascade ("Mustache layer later, not here" was misleading)2. Compress remaining launch schedule to daily cadence
Posts 1–3 ran on the original every-2-days cadence (2026-04-21 → 2026-04-25). Posts 4–10 were postponed for last-mile framework work. Compressed to daily cadence resuming 2026-05-06, landing GA on 2026-05-12 (was 2026-05-09). Blog 09
publishedAtfrontmatter updated to match.No code changes
ConfigLoader.cfcedit is comment-only — replaces the misleading "Mustache layer later" docstring with the truth (Mustache isinit-only). Diff stat: +88 / −63 lines, all prose/comment.Test plan
docs:type, no scope, header < 100 chars)pnpm --filter @wheels-dev/site-guides build)09-wheels-deploy.md,migrating-from-kamal.mdx,architecture.mdx,config-reference.mdxfor claritysocial-announcements.mdwheels deploy versionstill printswheels-deploy mirrors kamal 2.4.0 / kamal-proxy v0.8.6(unchanged — no code touched)