Description
Currently, post-app-boot is a global hook that triggers only after all roles on a server have booted. In multi-role deployments, this creates a race condition where the primary role (e.g., web) becomes healthy and starts serving traffic before the post-app-boot hook have executed.
The Problem
If a deployment includes breaking database changes, the web role will serve errors during the window while Kamal is still booting secondary roles (e.g., workers or background-jobs).
The API is "live" and receiving requests, but the database has not yet been migrated because the global hook is waiting on the remaining roles to finish their boot sequence.
Proposed Solution
Introduce role-specific post-app-boot hooks within the roles configuration. This should define a command to be executed via docker exec inside the newly started container immediately after it passes its health check, rather than waiting for the entire deployment sequence to complete.
Example deploy.yml:
roles:
web:
hosts: [1.2.3.4]
hooks:
post-app-boot: "uv run alembic upgrade head" # Runs as soon as 'web' is healthy
worker:
hosts: [1.2.3.4]
hooks:
# Alternative: running a custom shell script inside the container
post-app-boot: "scripts/setup-worker.sh"Goal
To ensure the environment is synchronized with the application code the moment a role begins accepting traffic, eliminating the "breaking change" error window caused by sequential role booting.
Description
Currently,
post-app-bootis a global hook that triggers only after all roles on a server have booted. In multi-role deployments, this creates a race condition where the primary role (e.g.,web) becomes healthy and starts serving traffic before thepost-app-boothook have executed.The Problem
If a deployment includes breaking database changes, the
webrole will serve errors during the window while Kamal is still booting secondary roles (e.g.,workersorbackground-jobs).The API is "live" and receiving requests, but the database has not yet been migrated because the global hook is waiting on the remaining roles to finish their boot sequence.
Proposed Solution
Introduce role-specific
post-app-boothooks within the roles configuration. This should define a command to be executed via docker exec inside the newly started container immediately after it passes its health check, rather than waiting for the entire deployment sequence to complete.Example
deploy.yml:Goal
To ensure the environment is synchronized with the application code the moment a role begins accepting traffic, eliminating the "breaking change" error window caused by sequential role booting.