A deployment in Compartment is a single build-and-run instance of one service in one environment. Every time you runDocumentation Index
Fetch the complete documentation index at: https://docs.compartment.dev/llms.txt
Use this file to discover all available pages before exploring further.
compartment deploy, Compartment creates a new deployment for each affected service, builds it, and then promotes it through a sequence of stages until it becomes the active deployment serving live traffic — or marks it failed if something goes wrong. The previous active deployment keeps running until the new one is fully healthy, giving you zero-downtime rollouts without any extra configuration.
Deployment lifecycle
A deployment passes through two parallel tracks as it makes its way to active: a runtime status and a promotion stage.Runtime status
The runtime status describes the overall execution state of the deployment operation:| Status | Meaning |
|---|---|
queued | The deployment has been accepted and is waiting for a build slot. |
running | The deployment is actively progressing through its promotion stages. |
succeeded | The deployment reached the active promotion stage and is now serving traffic. |
failed | The deployment stopped progressing due to a build error, readiness failure, or other problem. |
Promotion stages
The promotion stage gives you finer-grained visibility into exactly where in the pipeline a running deployment is:| Stage | What Compartment is doing |
|---|---|
building | Compiling or packaging the service image. |
starting_candidate | Launching the new container alongside the current active deployment. |
checking_readiness | Polling the service’s readiness endpoint and waiting for a healthy response. |
switching_route | Shifting live traffic from the previous active deployment to the new one. |
draining_previous | Waiting for in-flight requests to the old container to complete before stopping it. |
active | The deployment is live and serving all traffic. |
rolled_back | The deployment was previously active but was superseded by a rollback operation. |
Health states
Each deployment also carries a health state that reflects the runtime condition of its container:| Health | Meaning |
|---|---|
pending | Health has not yet been determined (container is still starting). |
healthy | The container is running and passing readiness checks. |
unhealthy | The container has failed its readiness check or crashed. |
Zero-downtime promotion
Compartment’s zero-downtime model works because the new deployment (the “candidate”) runs alongside the current active deployment duringstarting_candidate and checking_readiness. Traffic does not switch until the candidate is confirmed healthy.
Deployment data
Each deployment exposes the following fields, which you can inspect withcompartment status or compartment inspect:
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier for this deployment. |
serviceName | string | The service this deployment belongs to. |
status | runtime status | Overall execution state: queued, running, succeeded, failed. |
health | health state | Container health: pending, healthy, unhealthy. |
promotionStage | promotion stage | Current stage in the promotion pipeline. |
isActive | boolean | Whether this deployment is currently serving live traffic. |
routeUrl | string or null | The live URL for routable services (web, api). Null for background services. |
failureMessage | string or null | Human-readable reason if the deployment failed. |
createdAt | datetime | When the deployment was created. |
completedAt | datetime or null | When the deployment reached a terminal state. |
Inspecting deployments
Usecompartment status to see the current state of all deployments in an environment:
compartment logs to stream or fetch recent output from a running deployment:
Log streams
Each deployment produces output across three log streams:| Stream | Content |
|---|---|
compartment | Platform-level events: build output, promotion stage transitions, errors. |
stdout | Standard output from the running container process. |
stderr | Standard error from the running container process. |
Rollback
If an active deployment causes problems, you can roll back to the previous active deployment for a service without rebuilding:active and marks the current active deployment as rolled_back. The rollback itself is a promotion-stage transition, so it goes through switching_route and draining_previous — preserving zero-downtime behavior even during rollback.
Deployment logs example
The following snippet shows what a typical deployment log stream looks like, including thecompartment stream events for promotion stage changes:
Next steps
Promote and rollback guide
Hands-on guide to promoting candidates and recovering from a failed deployment.
Environments
Learn how environments isolate deployments and variables across your release stages.
Services
Configure readiness checks and other per-service settings that govern promotion.
CLI: deploy command
Full reference for
compartment deploy flags and options.