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.

Last updated 18 November 2026View as Markdown

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 POST /deploy/api/deployments/{id}/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.

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:

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.

Did this page help you?