The deploy trace
What happens during one deploy, step by step.
One deploy, from the trigger to a running container: the steps behind most error messages.
Something triggers it
| Trigger | Comes from |
|---|---|
| Deploy or Redeploy in the dashboard | A person |
| A push to the tracked branch, or a new tag | The git provider's webhook |
A POST to the app's deploy hook URL | CI, a script, a provider Deplo cannot register a webhook with |
| A pull request opened or updated | Previews, if they are on |
| The MCP server or the GraphQL API | A token with deploy_apps |
Watch paths skip an automatic deploy when the push touched nothing under them. A manual redeploy always runs.
It waits for a slot
Each server runs 1 deploy at a time by default, so deploys to one machine queue while other
servers work in parallel. Two deploys of the same app never overlap. A queued deploy shows its
position in the build log. An app built on a build server waits for a
slot on that machine.
The agent fetches the source
The control plane hands the job, decrypted credentials included, to the agent on the target server. A Git source is cloned with the git connection's token (submodules too, if asked, from the same git server only). An Upload uses your archive. Docker image and Compose skip this step.
The build method is picked
On Automatic, the default, Deplo looks in the root directory on every deploy: a Dockerfile
is built, else a Compose file is deployed as a stack, else Railpack builds the app. The log says
which one ran. A method you picked yourself is used as it is.
Under Railpack, Deplo also recognises the framework from package.json and the root config on
every deploy, and shows it on the app. Railpack works out the install, build and start commands
unless you typed your own.
The image is built
Railpack makes a build plan from the detected language and framework, Dockerfile builds
your Dockerfile (optionally one stage), Compose builds the services of your Compose file.
One build step may use about 75% of the server's memory. Past that the build stops and says so,
and the apps already running there keep theirs. Every environment variable is available during
the build too, so values like NEXT_PUBLIC_* work.
The image stays on that server: Deplo pushes to no registry. Build output streams live, survives a page reload or a control plane restart, and is capped at 20,000 lines of 4,000 characters.
The environment is resolved
Four layers, lowest priority first:
- Shared variables injected everywhere (owned by the instance or reaching several teams)
- The app's own variables
- A shared variable the app has linked
- A preview override (previews only)
The highest layer that defines a name wins. A preview built from a fork gets only the plain preview overrides, never the app's own values.
The stack is rendered
On the control plane, never on the server:
- The Compose file: one service for a single-image app, or your stack with Deplo's entries.
- The Traefik labels: one route per domain; path routes win over whole-host ones, longest first.
- The port, the volumes, the resource limits and the mounts.
The agent receives finished YAML: no routing logic lives on the server.
The agent starts it
The agent writes the stack and a private environment file next to it, then runs Compose. The
containers join the app's Environment network (deplo-env-<id>), the team's
deplo-team-<id> when the app is in no Environment, or deplo-preview-<key> for a preview. Traefik
sees the new labels and starts routing.
It checks that the app runs
A deploy is ready only when the app really runs:
- It stays up for 10 seconds after it starts: no exit, no restart.
- An app with a domain answers on its port. An app with none only has to stay up, so a background worker deploys fine.
- A slow starter gets up to 3 minutes.
A crash, a restart loop, or an app that never listens (or listens only on 127.0.0.1) fails the
deploy; the log says why and shows the app's last lines. If it listens on another port, for
example 8080 instead of 3000, Deplo routes to 8080, saves it as the app's port and says so.
See The port is the one people get wrong.
The result is recorded
The deployment gets its final status, image, duration and logs. The app's status becomes
active, or error if the build or the start failed.

Images older than the app's rollbacks kept setting (default 3) can be removed by the
server's disk cleanup, and a removed image is gone. An app from a repository can still roll back
by rebuilding that commit.
A picture is taken
Once the deployment is live, the app's server opens it in a private browser and takes a picture in light and dark. It becomes the cover of the Production Deployment card and of the deployment's page.
- Cookie banners are dismissed with Reject for the consent tools Deplo knows. For any other, hover the cover and use Retake screenshot.
- Ads and analytics are not loaded, so the picture never counts as a visit.
- Basic auth: Deplo signs in with the app's credentials, never for a fork's pull request.
- No picture when the page errors, stays blank, or the app has no domain. Deplo retries once a minute later, then waits for the next deploy.
- No private network: the browser goes out only through the server, which refuses private addresses.
Turn it off in Settings -> Advanced -> Deployment screenshots, which also deletes the saved ones.
What a deploy does not do
- It does not touch your data or identity. Volumes are reattached, never recreated; the slug and volume names stay.
- It does not roll back on failure. A failed build leaves the previous version running. An app that fails the start check has already replaced it: roll back to the last version that worked, or turn on zero-downtime deploys. See App status.
Zero-downtime deploys
Beta, off by default. Turn it on per app in Settings -> Advanced -> Zero-downtime deploys. It applies from the next deploy.
Normally the old container stops before the new one starts, so the app is offline while it boots. With zero-downtime deploys on, a redeploy keeps the old version online until the new one is ready:
- A copy of the new version starts beside the old one. It gets no traffic until it answers on its port.
- Traffic is shared between the two once the copy is ready.
- The old container is replaced while the copy serves.
- The copy is removed once the new container is ready.
Apps that reach this one by its name keep reaching a running copy the whole time.
If the new version never gets ready, the copy is removed, the deploy fails, and the old version never stopped. One exception: an app with storage (a volume, a host folder or Files) may refuse a second copy, for example a lock file or an embedded database. Deplo then removes the copy and swaps in place, so the deploy still goes through, with the usual short outage.
It swaps in place instead, and the log says why, when:
- the app publishes ports on the server: two copies cannot hold the same port
- the deploy changes the app's domains
- nothing is running yet (the first deploy, or a stopped app)
- the server's agent is too old, or its Docker is older than version 25
Good to know:
- Compose stacks swap in place, and the setting is shown only for single-image apps. A stack
with a service that sets
deploy.replicasabove 1 deploys beside itself instead. See Compose stacks. - An app with more than one replica always deploys this way, whatever the switch says. See How a deploy goes.
- The new version starts twice, once as the copy and once as the container. A migration that runs at startup runs twice, and the old version is still serving while it runs.
- Without a health check of its own, the app gets one that checks its port is open. The proxy sends traffic only to a container whose check passes.
- A second or two of errors is still possible while a stopped container leaves the proxy.
A rollback is much shorter
Steps 3 to 5 are skipped: no fetch, no build. Deplo runs an existing image again with the current configuration, so the code goes back while the variables, domains, volumes and limits do not. It is recorded as a real deployment with its own logs.
Next steps
Did this page help you?