Add idle service configuration for kamal-proxy

[komagata]

Summary

Add Kamal configuration for the opt-in idle service support in basecamp/kamal-proxy#228.

This continues the work started by @martijnenco in #1800. Thank you for providing the original configuration approach.

Behavior

Applications can configure idle shutdown and wake timeout in deploy.yml:

proxy:
  idle:
    timeout: 300
    wake_timeout: 30

When at least one role enables idle mode, Kamal:

• passes idle timeout options to kamal-proxy during deploy
• mounts the configured Docker socket into the proxy container
• adds the socket's numeric host group ID to the proxy container
• passes the socket path to the proxy process

When idle mode is not configured, generated proxy run and deploy commands remain unchanged and the Docker socket is not mounted.

Direct Docker access is intentionally opt-in and grants powerful host-level container control. The tradeoff and possible restricted host-side lifecycle service were discussed in basecamp/kamal-proxy#222.

Validation

• bin/test test/configuration/proxy_test.rb test/configuration/proxy/run_test.rb test/commands/proxy_test.rb test/commands/app_test.rb
• 145 runs, 191 assertions, 0 failures, 0 errors
• git diff --check origin/main...HEAD
• Generated run/deploy commands were validated against real Docker and Add opt-in scale-to-zero for idle services kamal-proxy#228 on a 2 GB Ubuntu VPS

Detailed results and reproduction instructions: https://docs.komagata.org/6456

[Copilot]

Pull request overview

Adds opt-in configuration for kamal-proxy “idle services” (scale-to-zero) in Kamal, including passing idle timeouts to kamal-proxy and enabling Docker socket access only when idle mode is configured.

Changes:

• Introduces proxy.idle.timeout / proxy.idle.wake_timeout configuration and validation.
• Extends generated proxy deploy/run commands to include idle flags and (when enabled) mount/configure the Docker socket for lifecycle operations.
• Updates documentation and adds tests covering the new configuration and command output.

Tip

If you aren't ready for review, convert to a draft PR.
Click "Convert to draft" or run gh pr ready --undo.
Click "Ready for review" or run gh pr ready to reengage.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
lib/kamal/configuration.rb	Adds a helper to detect whether proxy idle mode is enabled anywhere in the config.
lib/kamal/configuration/proxy.rb	Adds idle? and wires idle options into proxy deploy flags; ensures proxy run config exists when idle is enabled.
lib/kamal/configuration/validator/proxy.rb	Validates idle timeout / wake timeout constraints.
lib/kamal/configuration/proxy/run.rb	Adds docker socket flag + mount/group wiring into proxy container run args when idle is enabled.
lib/kamal/configuration/docs/proxy.yml	Documents proxy.idle and proxy.run.docker_socket.
test/configuration/proxy_test.rb	Adds tests for parsing/validating idle configuration and deploy option output.
test/configuration/proxy/run_test.rb	Adds tests for selecting default/custom docker socket paths under idle mode.
test/commands/proxy_test.rb	Verifies proxy docker run command includes socket mount/group-add and socket arg only when idle is enabled.
test/commands/app_test.rb	Verifies deploy command includes idle flags when configured.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated no new comments.

[komagata]

Hi! The corresponding kamal-proxy implementation in basecamp/kamal-proxy#228 has now been rebased onto the latest main. go test ./..., the race tests, and go vet ./... are all passing.

Since these two PRs need to be considered together, I’d appreciate guidance on whether opt-in scale-to-zero support fits the direction of Kamal and kamal-proxy. If the direction is acceptable, I’m happy to adjust the implementation or split the changes into smaller PRs to make review easier. Thanks!

[komagata]

@djmb, would you be able to advise whether this direction fits Kamal? The corresponding kamal-proxy implementation is in basecamp/kamal-proxy#228 and is up to date with main. Thank you!