# Deployments

A deployment is one attempt to put a specific image or compose file live; this page covers its statuses, what it does step by step, its timeline and how long it is kept.

Each deployment of an app has a **generation** number. The newest live generation is what the
app's domains serve. Only one deployment of an app runs at a time; a second one supersedes the
first.

## Statuses

| Status       | Meaning                                                                  |
| ------------ | ------------------------------------------------------------------------ |
| `queued`     | accepted, not started                                                    |
| `building`   | the platform is building an image from a repository                      |
| `pushing`    | the image is being pushed to your registry                               |
| `deploying`  | the machine is pulling and starting it                                   |
| `live`       | the published service answered, and the domain points at this generation |
| `failed`     | a step did not complete; its cause is the last line of **Activity**      |
| `superseded` | a newer deployment of the same app replaced this one before it finished  |

A deployment that has not finished (`queued`, `building`, `pushing` or `deploying`) can be
stopped with **Cancel** on its **Activity**, then **Cancel deployment**, or
`deploy.deployments.cancel`; both need `deploy:DeployApp` on the app. The pipeline stops at the
end of the step it is in and the deployment becomes `failed` with "Cancelled from the console by"
and your user name as its cause. The generation that was serving keeps serving. A deployment that
has already finished answers `409` with "This deployment is already …, so there is nothing left
to stop."

## What a deployment does

1. An image in your registry is resolved to its digest; the app is bound to that repository so its
   machine may pull it.
2. The machine logs in to every registry the app holds a credential for, then pulls.
3. The release command, if the app has one, runs from the new image. Its output streams to the
   activity feed. A non-zero exit fails the deployment here. For an image app this is before
   anything is started or stopped; for a compose app it is before anything is stopped, except on a
   first deployment or when a service the release depends on is replaced, where it runs once those
   services are up.
4. The new container starts and must pass its health check within `timeoutSec`.
5. Traffic moves to the new container and the old one is removed.

Without a `healthCheck`, the published service must answer `GET /` with a status below 500 within
60 seconds for an image app and 180 seconds for a compose app. A deployment whose machines have
not reported healthy within 8 minutes is `failed`; when the deployment had to create a new machine
first, the limit is 20 minutes, since the machine installs its software before it can report. An
image build that has not pushed an image within 15 minutes fails the deployment. In every failure, the version that was serving
keeps serving.

## What a redeploy does on the machine

| App     | Behaviour                                                                                                                                                                                                                                                                                        |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| image   | the new container starts on a new port beside the old one; once it answers, the domain moves; the old container is removed. No downtime.                                                                                                                                                         |
| compose | each service whose definition changed (image, environment, mounts, command) is stopped and started again; services whose definition did not change are left running untouched. A changed service is down for the seconds it takes to start. The domain moves once the published service answers. |

## The timeline

Each row of **Deployment history** on the **Deployments** tab has a phase bar: how long the
deployment waited, built, pushed its image and rolled out, with the total, and who started it and
why. The **Overview** shows the same breakdown for the newest deployment. Each finished deployment
also records its duration and outcome as metrics of the app; see [Monitoring](monitoring.md).

The deployment's **Activity** lists every step, each marked as reported by the machine itself or
written by the platform, and updates every 3 seconds while the deployment runs. Over the API:

```sh
dcloud deploy deployments events deployment-id
dcloud deploy deployments wait deployment-id --timeout-sec 55
```

Replace deployment-id with the deployment's id. `wait` returns as soon as the deployment is
`live`, `failed` or `superseded`, or after `timeoutSec` (at most 55) with `terminal: false`; call
it again until it is terminal. A failed deployment includes its error events.

## How long deployment history is kept

Every app keeps its newest 50 deployments, the live one, any still rolling out, and every
deployment from the last 30 days. Older ones are removed once a day with their build logs; the
app's activity says which. The container registry keeps the images of an app's last ten
deployments whatever its lifecycle rules say, so a rollback to any of them still pulls.

## Related

- [Deploy an app](deploy-an-app.md)
- [Roll back a deployment](roll-back-a-deployment.md)
- `deploy.deployments.create` · `dcloud deploy deployments create`
