Wheels 4.0 ships wheels deploy — a Kamal port, no Ruby required

[bpamiri]

Wheels 4.0 introduces a new built-in command: wheels deploy. It is a port of Basecamp's Kamal — the container-based deployer — into the Wheels CLI. This post is for anyone currently running ad-hoc deploy scripts (or running Ruby Kamal alongside Wheels) who wants to understand what's shipping and what the contract is.

Full blog post: https://blog.wheels.dev/posts/wheels-deploy-kamal-port/

Why a port, not a plugin

Wheels ships as a LuCLI binary (CFML + Java). Asking users to gem install kamal adds a Ruby runtime dependency and a second CLI to learn. Kamal's proxy component (kamal-proxy) is already a standalone Go binary — what's Ruby-specific is only the developer-side orchestrator that opens SSH connections, uploads config, and runs docker commands. So we ported the orchestrator, left kamal-proxy untouched, and kept the on-server state byte-compatible.

What's byte-compatible

Everything in this list matches the Kamal 2.4.0 contract exactly:

Concern	Value
Container name	<service>-<role>-<version>
Container labels	service=, role=, destination=, version=
Docker network	kamal
Proxy image	basecamp/kamal-proxy:v0.8.6
Proxy config dir	/home/<user>/.config/kamal-proxy/
Lock file path	/tmp/kamal_deploy_lock_<service>
Audit log	/tmp/kamal-audit.log
Hook directory	.kamal/hooks/
Hook env prefix	KAMAL_* (not WHEELS_* — so existing Kamal hook scripts work unchanged)
Secret file	.kamal/secrets, .kamal/secrets.<destination>

A server managed by Ruby Kamal can be taken over by wheels deploy during evaluation, and vice versa. You can run both tools against the same host while you decide.

The one divergence

config/deploy.yml does not support ERB. ERB is Ruby template code; rendering it from a CFML CLI would require embedding a Ruby runtime, which defeats the purpose of the port. What Wheels keeps unchanged is Kamal's other built-in interpolation — ${UPPER_SNAKE} env-var tokens — so most ERB-using configs convert mechanically:

# Ruby Kamal — NOT SUPPORTED
service: <%= ENV["APP_NAME"] %>
image: <%= ENV["REGISTRY"] %>/<%= ENV["APP_NAME"] %>

# wheels deploy — and also valid Kamal syntax
service: ${APP_NAME}
image: ${REGISTRY}/${APP_NAME}

${VAR} references resolve through the same lookup chain Kamal uses (.kamal/secrets → process environment variables → empty string). For ERB blocks that did real logic — conditionals, ternaries, computed values — the resolution moves into .kamal/secrets (or a .kamal/secrets.<destination> overlay) and the result is referenced back through ${VAR}.

Net effect: there is no new syntax to learn. The single change is a removal — ERB out, everything else identical.

Subcommand surface

Mirrors Kamal's top-level verb structure:

• Top-level: init, setup, rollback, config, version, details, audit, remove, docs
• App: app boot | start | stop | details | containers | images | logs | live | maintenance | remove
• Proxy: proxy boot | reboot | start | stop | restart | details | logs | remove
• Accessory: accessory boot | reboot | start | stop | restart | details | logs | remove — for sidecars (database, cache, search)
• Build: build deliver | push | pull | create | remove | details | dev
• Registry: registry setup | login | logout | remove
• Server: server exec | bootstrap
• Prune: prune all | images | containers
• Lock: lock acquire | release | status (normal deploys auto-lock)
• Secrets: secrets fetch | extract | print with adapters for 1Password, Bitwarden, AWS Secrets Manager, LastPass, Doppler

Every verb supports --dry-run — prints the exact shell commands that would run remotely without opening an SSH connection. The commands-layer test suite runs offline, no Docker, no sshd.

What wheels deploy is not

• Not Kubernetes. It drives docker remotely over SSH. For k8s, use your normal pipeline.
• Not systemd-native. For VM or bare-metal non-container deploys, see the VM deployment guide.
• Not Compose-only. Single-host Compose is covered by a different doc; wheels deploy adds value at two or more servers.
• Not for Windows servers. Linux targets only. Windows developer workstations are best-effort.
• Not a Wheels reload mechanism. Ships the container; the in-process ?reload=true story is separate.
• Not Ruby-Kamal-plugin-compatible. Shell-script hooks in .kamal/hooks/ work unchanged; the Ruby-plugin extension API is Ruby-specific.

Docs

• Deployment landing page — start here for context and when-to-use guidance
• Your first deploy — hands-on walkthrough
• Migrating from Kamal — the full compatibility contract and switch-over checklist
• Config reference, secrets, hooks, accessories

Question for the thread

If you're currently deploying a Wheels app to production, what does your setup look like today — and what would stop you from trying wheels deploy? The design space is still open for 4.0.x polish.