# Configure the release command and health checks

Run a command such as a database migration once per deployment before traffic moves, and decide when a new container counts as ready.

Both settings take effect on the next deployment; the running generation keeps what it started
with. Replace app-id with the app's id.

## Prerequisites

- Permission for `deploy:UpdateApp` on the app. Without it the console does not show the **Release
  and health checks** section.
- An image with `/bin/sh`: the release command runs with `/bin/sh -c`, replacing the image's
  entrypoint.
- In the console, also `deploy:DescribeApp` to open the app's page (without it the page is not
  found).

## Configure them

**Console**
1. Open the app, then choose the **Runtime** tab.
2. Under **Release and health checks**, for **Release command**, enter the command, for example
   `pnpm db:migrate`. Leave it empty for none.
3. (Optional) For **Release timeout (seconds)**, enter a value from 10 to 3600.
4. For **Health check path**, enter a path the app answers, for example `/api/health`.
5. (Optional) For **Health check port**, **Expected status** and **Health check timeout
   (seconds)**, enter values. Empty fields use the defaults: the app's port, any status below 500,
   60 seconds (180 for a compose app).
6. Choose **Save**. **Saved** appears beside the button.

The release service and the checks of other compose services are not in the console; set them with
the CLI, API or Terraform.

**CLI**
```sh
dcloud deploy apps update app-id \
  --release-command 'pnpm db:migrate' \
  --health-check '{"path":"/api/health","expectedStatus":200,"timeoutSec":120}'
```

For a compose app, `--release-service worker` runs the release command from another service than
the published one, and `--compose-health-checks` adds checks for other services.

**API**
```http
PATCH /deploy/api/apps/3f1c2b4a-5d6e-4f70-8a91-b2c3d4e5f601
{
  "releaseCommand": "pnpm db:migrate",
  "releaseTimeoutSec": 600,
  "healthCheck": { "path": "/api/health", "expectedStatus": 200, "timeoutSec": 120 }
}
```

**Terraform**
```hcl
resource "dcloud_app" "web" {
  name                = "my-app"
  builder             = "image"
  image_ref           = "org-example1234.ecr.example.com/orders:1.4.2"
  release_command     = "pnpm db:migrate"
  release_timeout_sec = 600
  health_check        = jsonencode({ path = "/api/health", expectedStatus = 200, timeoutSec = 120 })
}
```

The update is refused with `400` for a value outside its range, and for a compose app whose pasted
file the change makes invalid (a release-only service that is not the release service, for
example); and with `409` while the app is being deleted. A release service that is not in the
compose file fails the next deployment before anything is rolled out.

## How the release command runs

The machine pulls the new image, then runs the release command in a throwaway container of it, with
the app's environment; for a compose app on the app's private network, so `db` resolves as it does
for the services. Its output appears in the deployment's activity line by line. Exit code 0
continues the rollout; anything else fails the deployment with `Release command exited with code
<n>; the previous version keeps serving.` A release that succeeded is not run again when the same
deployment is retried. A rollback runs the release command that shipped with the deployment it
rolls back to. The command is stopped, and the deployment fails, after `releaseTimeoutSec`
(default 600).

For a compose app, the release runs before anything is stopped when every service the release
service depends on is already running and unchanged. Otherwise (a first deployment, or a dependency
being replaced) it runs after those dependencies have started and passed their health checks, and
before the release service starts. To run it in an image the app does not serve, see
[Release-only services](compose-files.md#release-only-services).

The release command is handed to the app's machines until one of them reports that it succeeded.
Write it so that running it more than once is safe, as a migration tool's "apply pending
migrations" is.

## How health checks run

A new container is probed every 2 seconds until the check passes or `timeoutSec` runs out (default
60 seconds, 180 for a compose app's published service). With `expectedStatus` set, only that status
passes; without it any status below 500 passes. The same check runs with every report the machine
sends afterwards and drives the machine's health in the Deutsche Cloud Console. A compose service listed in
`composeHealthChecks` is waited for after it starts and before anything that depends on it starts
(default timeout 120 seconds); its `port` is required, and a check without one fails the
deployment on the machine. A check named for a service the file does not have fails the deployment
before anything is rolled out.

## Result

The next deployment runs the release command before traffic moves, and moves traffic only once the
health check passes.

## Related

- [Deployments](deployments.md)
- [Troubleshooting](troubleshooting.md)
- `deploy.apps.update` · `dcloud deploy apps update` · `dcloud_app`
