Health Checks & Post-deploy Commands
Health checks
Before Vessl promotes a new deployment to production, it runs a health check against the new container. If the health check passes, the swap happens. If it fails, the deploy is marked as failed and your current version keeps running.
Configuring the health check path
The health check is a GET request to a path on your app. It defaults to /.
To change it, set the Health Check Path field during app creation (in the Config step) or later from Settings → Runtime & Release → Health Check Path.
Common examples:
/— fine for most apps that return 200 at the root/health— a dedicated endpoint that checks database connectivity and other dependencies/api/status— for API-only apps
The health check passes when your app returns HTTP 200. Any other response code, or no response within the timeout, is treated as a failure.
Returning 200 at /health without actually checking your dependencies can mask issues. A good health endpoint verifies the database connection, cache connection, and any other critical service — and returns 200 only when everything is ready.
What happens on failure
If the health check fails during a deploy:
- The new container is stopped.
- The existing (old) container continues serving traffic.
- The deployment is marked as Failed in the Deployments tab with the reason.
- You can read the deploy logs to diagnose what went wrong.
No action is needed from you to "roll back" — the old version is already still running.
Post-deploy commands
A post-deploy command runs inside the newly deployed container, after the container is healthy and has been promoted to production, before Vessl marks the deploy as complete.
Set it in the Config step during app creation, or from Settings → Post-Deployment.
Common uses
Run database migrations automatically:
php artisan migrate --force
python manage.py migrate
bundle exec rails db:migrate
Clear application cache:
php artisan cache:clear && php artisan config:cache
Things to keep in mind
- The command runs after the new container is live and serving traffic. If your migration is destructive (drops a column the old code still needs), you can get errors briefly.
- If the post-deploy command exits with a non-zero code, the deploy is marked as failed. The container stays running, but Vessl flags the deploy as incomplete.
- The command runs in a login shell (
bash -l), so your app's PATH and environment are available. - For long migrations, set a generous health check timeout — the deploy won't complete until the command finishes.
If you deploy a migration that removes or renames something the current live code depends on, you may cause errors while the new container is starting. Use backwards-compatible migration patterns (add before remove, deploy in two steps) for schema changes that affect running code.
Add-on health checks
Databases and caches (PostgreSQL, MySQL, Redis) have their own optional Health Check under Service → Settings → Health Check. It is different from the app health check above:
- The app health check gates a deploy (an HTTP
GETthat must return 200 before the swap). - The add-on health check is a plain Docker
HEALTHCHECK: Docker runs a command inside the container on an interval and reports the container as healthy, unhealthy, or starting.
What it does — and doesn't do
It reports a health status. On its own it does not restart the container — Docker's restart policy reacts to a container that exits (crashes), not to one that is merely marked unhealthy. If you want a service to come back after a crash, use the Restart Policy setting.
You don't need to enable this just to be alerted. Vessl automatically probes every database and cache add-on every few minutes (Redis PING, Postgres pg_isready, MySQL mysqladmin ping) and emails the owner if an add-on stops responding — even while its container is still "running". The Docker health check is an optional extra that surfaces the status on the container itself.
Fields
| Field | What it maps to | Default |
|---|---|---|
| Test Command | --health-cmd — the shell command run inside the container | (empty = disabled) |
| Interval | --health-interval — how often the command runs | 30s |
| Timeout | --health-timeout — max wait for one check | 10s |
| Retries | --health-retries — consecutive failures before "unhealthy" | 3 |
The command runs inside the container's shell. Exit 0 = healthy, anything else = unhealthy.
Example commands per engine
| Add-on | Test command |
|---|---|
| Redis | redis-cli ping |
| PostgreSQL | pg_isready -U $POSTGRES_USER |
| MySQL / MariaDB | mysqladmin ping |
The engine-appropriate example is offered as a one-click chip in the UI, and pre-filled when you enable the check. Save the setting, then Redeploy the service to apply it (Docker reads the health-check config only when the container is created).