Deploying Changes

To deploy changes to your code you will first create a Release and then promote it.

Promoting a Release will begin a rolling deployment that will continue until the new Release is active on all Processes or has been completely rolled back.

One Step

To create a Release and promote it in one step, use convox deploy:

$ convox deploy -a myapp
Packaging source... OK
Uploading source... OK
Starting build... OK
...
Build: BABCDEFGHI
Release: RBCDEFGHIJ
Promoting RBCDEFGHIJ...
2026-03-18T14:30:49Z system/k8s/atom/app Status: Running => Pending
2026-03-18T14:30:51Z system/k8s/web Scaled up replica set web-745f845dc to 1
2026-03-18T14:30:51Z system/k8s/web-745f845dc Created pod: web-745f845dc-rzl2q
2026-03-18T14:30:51Z system/k8s/web-745f845dc-rzl2q Successfully assigned convox-myapp/web-745f845dc-rzl2q to instance-0a1b2c3d4e5f
2026-03-18T14:30:51Z system/k8s/web-745f845dc-rzl2q Pulling image "registry.host/convox/myapp:web.BABCDEFGHI"
2026-03-18T14:30:53Z system/k8s/atom/app Status: Pending => Updating
2026-03-18T14:30:55Z system/k8s/web-745f845dc-rzl2q Successfully pulled image "registry.host/convox/myapp:web.BABCDEFGHI"
2026-03-18T14:30:56Z system/k8s/web-745f845dc-rzl2q Created container main
2026-03-18T14:30:56Z system/k8s/web-745f845dc-rzl2q Started container main
OK

Two Steps

You can also perform the steps of creating the Release and promoting it with two different commands. This is useful if you would like to make changes to Environment Variables or run migrations against the new Release before it is pushed live.

$ convox build -a myapp
Packaging source... OK
Uploading source... OK
Starting build... OK
...
Build: BABCDEFGHI
Release: RBCDEFGHIJ

$ convox releases promote RBCDEFGHIJ -a myapp
Promoting RBCDEFGHIJ...
2026-03-18T14:30:49Z system/k8s/atom/app Status: Running => Pending
2026-03-18T14:30:51Z system/k8s/web Scaled up replica set web-745f845dc to 1
2026-03-18T14:30:51Z system/k8s/web-745f845dc Created pod: web-745f845dc-rzl2q
2026-03-18T14:30:51Z system/k8s/web-745f845dc-rzl2q Successfully assigned convox-myapp/web-745f845dc-rzl2q to instance-0a1b2c3d4e5f
2026-03-18T14:30:51Z system/k8s/web-745f845dc-rzl2q Pulling image "registry.host/convox/myapp:web.BABCDEFGHI"
2026-03-18T14:30:53Z system/k8s/atom/app Status: Pending => Updating
2026-03-18T14:30:55Z system/k8s/web-745f845dc-rzl2q Successfully pulled image "registry.host/convox/myapp:web.BABCDEFGHI"
2026-03-18T14:30:56Z system/k8s/web-745f845dc-rzl2q Created container main
2026-03-18T14:30:56Z system/k8s/web-745f845dc-rzl2q Started container main
OK

External Builds

By default, convox build and convox deploy package the source directory into a tarball and upload it through the rack's load balancer for in-cluster building. For applications with large source directories (e.g., model weights, large binary assets), that upload can be slow.

The --external flag builds the Docker image on your local machine (or CI runner) and pushes it to the Rack, skipping the source upload entirely:

$ convox build --external -a myapp
$ convox deploy --external -a myapp

With external builds:

1. The CLI creates a Build record on the rack via a small API call
2. The Rack returns its own API endpoint, api.<rack domain>, as the registry to push to, with the Rack's credentials
3. Docker builds the image locally using your source directory
4. The CLI pushes the built image to the Rack API, which forwards it to the App's registry (ECR on AWS, ACR on Azure, Artifact Registry on GCP, and the registry the Rack runs itself on DigitalOcean and metal)
5. A Release is created on the rack referencing the pushed image (and promoted, if using convox deploy --external)

The source directory is never uploaded. External builds also benefit from local Docker layer caching for faster incremental rebuilds.

Requirements:

• Docker must be installed and running on the machine executing the build
• Docker on the machine must reach api.<rack domain> over HTTPS, including when the CLI reaches the Rack through the Console

External builds work on all v3 cloud providers and are well suited for CI pipelines that already have the source checked out. See the External Builds section of the build reference for the full CLI reference.

Troubleshooting Failed Deployments

If a deployment fails or hangs, use convox deploy-debug to diagnose the issue:

$ convox deploy-debug -a myapp

This command inspects your app's pods and provides actionable hints for common failure states like crash loops, image pull errors, OOM kills, and health check failures. See the deploy-debug reference for details.

See Also

• Rolling Updates for how Convox handles zero-downtime deployments
• Rollbacks for reverting to a previous release
• CI/CD Workflows for automating deployments
• build for the convox build command reference
• deploy for the convox deploy command reference