Deployments fail. A dependency changes, a migration is missing, an environment variable is wrong. What matters is whether the failure takes your running app down with it, and how much of the damage you can undo.
This guide covers the four controls that exist for that on Impreza, and is deliberate about their limits. None of them is a substitute for a backup.
What you get
- A health requirement that makes an unhealthy release count as a failure instead of a success
- Progress you can read: the named step the deployment is on, and a recorded history
- Cancellation while the work is still safe to stop
- Release history and manual rollback to a retained previous release
- Runtime health reported separately from the result of the last operation
Stop a bad release from being called good
By default, a deployment that starts its containers is treated as done. require_healthy_start changes that: the release only succeeds once your healthcheck_path answers 2xx, with no redirect, on the target port. It applies to the first install too, which is where the silent failures usually hide.
When a first install never becomes healthy, its containers are removed and its volumes are preserved. When a replacement fails, an eligible healthy previous release can be recovered. Requiring health needs agent 0.6.3 or newer, and it needs an explicit health path: there is no useful default for a route that means “ready”.
Read what is actually happening
Two different questions have two different answers, and mixing them up is the most common mistake.
The last operation tells you how the most recent deploy ended. Runtime health tells you what the containers are doing right now, which needs agent 0.6.4 or newer. A deployment can report success while the app is unhealthy, and it can report failure while the previous release keeps serving traffic perfectly.
Progress reporting, from agent 0.6.6 onward, gives you the named step the deployment is on, along with a bounded history of the steps it passed. It is a step, not a live percentage: nothing here estimates a finish time. If the agent restarts mid deploy, the saved result can still be read afterwards, and a guarded recovery path exists for a host reboot.
Keep a failed new version away from traffic
For eligible custom web apps on Agent 0.6.27 or later, an optional redeploy checks the new version before moving the managed route. If the new version never becomes ready, the previous one keeps serving. Read the final outcome and confirm the current route before retrying; a cleanup or recovery warning still needs review.
With Agent 0.6.30 or later, that prepared swap no longer reloads the managed proxy to move traffic. The replacement is checked before the old container stops. For Git redeploys, the build-context exchange preserves the previous directory and restores it if the exchange fails between its two renames. Read the result before retrying; these protections do not reverse shared-data changes or replace a backup.
See redeploying after readiness checks for eligibility and the proxy-only access change. This does not restore modified database data, apply to every app topology or guarantee zero dropped requests.
When an interrupted operation cannot continue
Agent 0.6.26 reports a readable failed result when an interrupted operation cannot continue and will not be repeated. If preparation recovery was verified, the result explains what was restored. If it could not be verified, the result says so and asks you to retry explicitly. A stopped deployment worker that leaves no final result no longer keeps later commands for that server waiting.
Before retrying, read the original command’s final result and check the app’s current runtime health. Do not assume that a missing response means nothing changed. If the result requires recovery review, keep the command ID and contact support before repeating a change to important data.
Existing servers need an explicit Agent update for this behavior. It does not guarantee that every interrupted deployment can be recovered or that a retry will succeed.
Follow the reported next step
For recognized failure types, current API and MCP responses include a readable error code and suggested next steps. Read the original operation and current runtime first, then select the smallest supported action. A permission error needs the right authorized connection; a missing backup needs a real recovery point. Repeated requests do not turn either condition into success.
Agent 0.6.28 preserves the existing source when a new Git clone or pinned-commit checkout fails. Its readiness checks also account for recent restarts and a sidecar that keeps crashing. These checks help avoid a false successful deployment; they do not restore mutable database data.
Keep an Agent update separate from app recovery
Agent 0.6.29 observes its service for 30 seconds after installing an update and restores the previous Agent version if the service restarts in that window. Check that the Agent reports again afterward. A failure outside the window still needs investigation, and Agent rollback is not an application or database restore. Existing machines update only when you request it; follow the Agent update guide.
Cancel, while cancelling still means something
Read the current operation first
Check the command identifier and the cancellation state of the operation you intend to stop. Cancelling blind is how people cancel the wrong deploy.
Cancel queued work
Work that has not started yet is cancelled immediately. This is the clean case.
Request a stop during preparation
Preparation returns requested, not cancelled. The agent stops at a safe point and restores the previous configuration, and only then does the state become terminal. Running cancellation needs agent 0.6.5 or newer.
Poll until it is terminal
Keep reading the operation until it reports cancelled or another final result. Never treat requested as confirmation that the work stopped.
A request stops the deployment at the next safe point, which may not be immediate. Once container replacement or recovery has started, it cannot be cancelled at all. Interrupting a build that is already running is only possible from agent 0.6.12, on supported Ubuntu 24.04 hosts, and only after the server administrator has enabled controlled builds.
Roll back to a previous release
Retained releases are listed with the deployment, each marked with whether rollback is supported. Pick one, confirm, and the platform restores it.
What comes back is the image and the configuration. What does not come back is your database, or any other mutable data. A rollback after a migration that rewrote a table restores old code on top of new data, which is usually worse than the failure you were fixing.
A rollback can also interrupt traffic while it happens, and it is reported as failed when the release has expired or when ports, storage or routing have changed since it was created. Read the deployment history for the real outcome rather than assuming the request succeeded.
Take a backup before shipping anything that changes the database, and know which volumes it covers. See app backups and restores. A copy taken while a database is writing is not proof of a consistent database.
For eligible branches, a temporary preview address lets the change be exercised before it reaches the live deployment. See previewing Git branches over Tor. Build credentials are never inherited by a preview, so a preview that needs them has to be given them deliberately.
The honest summary
The platform protects availability of the previous release. It does not protect your data, it does not guarantee an instant stop, and it does not switch traffic without interruption. Treat health requirements and release history as the seatbelt, and backups as the thing that actually restores what you lost.
Start now
Get an offshore VPS with the agent preselected, read deployment safety and rollback in the docs, or set the health policy while deploying with the Node, Python and PHP recipes.