#1846·kamal

Feature Request: Role-specific `post-app-boot` hooks

Author: CCXLVCreated May 1, 2026Updated Jun 21, 2026

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:

yaml
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.