Deployment Overview

Convoy Cloud supports three deployment modes. All three produce a running container in an isolated environment managed by the platform.

Deployment modes

Dockerfile

If your repository contains a Dockerfile, Convoy Cloud builds the image from it using BuildKit. This gives you full control — install any dependencies, run build scripts, configure your runtime, and optimise image size with multi-stage builds.

Best for:

• Applications with specific build requirements
• Multi-stage builds for smaller images
• Projects that already have a Dockerfile
• Monorepos with custom build contexts

Dockerfile deployments

Buildpack

If your repository does not contain a Dockerfile, or if you prefer zero-config builds, Convoy Cloud uses Railpack to automatically detect your language and framework, install dependencies, and produce a production-ready container image.

Best for:

• Quick deployments without a Dockerfile
• Standard web apps and APIs
• Getting started fast

Buildpack deployments

Existing image

Deploy a pre-built container image from Docker Hub or GitHub Container Registry. No build step runs. Convoy Cloud pulls your image directly and deploys it.

Best for:

• Images built in your own CI pipeline
• Public images you want to run unchanged
• Workflows where you control the build separately

Existing image deployments

Build pipeline (code-source modes)

For Dockerfile and buildpack deployments, every deploy goes through the same observable phases:

Validation -> Build -> Push -> Deploy -> Live

1. Validation — capacity and configuration are checked before work starts
2. Build — your code is compiled into a container image (live build logs stream in real time)
3. Push — the image is stored in Convoy Cloud's private registry
4. Deploy — the image is rolled out to your isolated namespace
5. Live — your application is serving traffic with TLS and routing in place

Persistent storage

Every app automatically receives a 4 GiB persistent volume mounted at /data. Data written there survives container restarts and redeployments. It is deleted when the app is deleted.

Build caching

Convoy Cloud caches builds to speed up redeployments:

• Build deduplication — if the same repo, commit, and build method have been built before (by any workspace), the cached image is reused immediately. The deploy wizard shows "Cached build available" when this applies.
• Layer caching — Dockerfile builds cache intermediate layers.
• Buildpack caching — buildpack builds maintain a per-repository dependency cache.

Force a fresh build by disabling Reuse Existing Build in the deployment wizard.

Live build logs

During a build, logs stream in real time on the deployment detail page. If a build fails, the logs show exactly where and why. Logs are also available on completed deployments from the deployment history panel.

Auto-rollback

If a deployment fails after the previous version was serving traffic, Convoy Cloud automatically rolls back to the last known-good image. A circuit breaker prevents repeated automatic rollbacks if failures recur within a short window — after two failures in 10 minutes, auto-rollback is suspended for one hour. All rollback activity is recorded in the Audit log.