deploy

deploy

Create and promote a build

Usage

    convox deploy [dir]

Flags

Flag	Short	Type	Description
--build-args		string	Build arguments (repeatable). Requires rack version 3.22.0+
--description	-d	string	Description for the build
--development		bool	Build in development mode
--external		bool	Use external build
--force		bool	Promote without waiting for the app to be ready; also reduces the environment drop guard message to a one-line notice and bypasses the guard when CONVOX_ENV_DROP_GUARD=strict
--id		bool	Output only the build/release ID
--manifest	-m	string	Path to an alternate manifest file
--no-cache		bool	Build without using the Docker cache
--wildcard-domain		bool	Use wildcard domain for the build

Examples

    $ convox deploy
    Packaging source... OK
    Uploading source... OK
    Starting build... OK
    Authenticating https://index.docker.io/v1/: Login Succeeded
    Authenticating 1234567890.dkr.ecr.us-east-1.amazonaws.com: Login Succeeded
    Building: .
    ...
    ...
    Running: docker tag convox/myapp:web.BABCDEFGHI 1234567890.dkr.ecr.us-east-1.amazonaws.com/test-regis-1mjiluel3aiv3:web.BABCDEFGHI
    Running: docker push 1234567890.dkr.ecr.us-east-1.amazonaws.com/test-regis-1mjiluel3aiv3:web.BABCDEFGHI
    Promoting RABCDEFGHI...
    ...
    ...
    2026-03-18T15:41:16Z system/k8s/atom/app Status: Running => Pending
    2026-03-18T15:41:18Z system/k8s/atom/app Status: Pending => Updating
    2026-03-18T15:41:27Z system/k8s/atom/app Status: Updating => Running
    OK

Pass build time env vars

You can pass env vars that will only exist at build time.

Build arguments require rack version 3.22.0 or later.

    $ convox deploy --build-args "BUILD_ENV1=val1" --build-args "BUILD_ENV2=val2"
    Packaging source... OK
    Uploading source... OK
    Starting build... OK
    Authenticating https://index.docker.io/v1/: Login Succeeded
    Authenticating 1234567890.dkr.ecr.us-east-1.amazonaws.com: Login Succeeded
    Building: .
    ...
    ...
    Running: docker tag convox/myapp:web.BABCDEFGHI 1234567890.dkr.ecr.us-east-1.amazonaws.com/test-regis-1mjiluel3aiv3:web.BABCDEFGHI
    Running: docker push 1234567890.dkr.ecr.us-east-1.amazonaws.com/test-regis-1mjiluel3aiv3:web.BABCDEFGHI
    Promoting RABCDEFGHI...
    ...
    ...
    2026-03-18T15:41:16Z system/k8s/atom/app Status: Running => Pending
    2026-03-18T15:41:18Z system/k8s/atom/app Status: Pending => Updating
    2026-03-18T15:41:27Z system/k8s/atom/app Status: Updating => Running
    OK

Environment Drop Guard

Because convox deploy creates a build, it runs the same environment drop guard as convox build (requires CLI version 3.25.1+). If variables set in the running release would be dropped by the new build, the CLI prints a warning to stderr with an explanation and an example convox env set KEY=... --promote command to keep them, and the deploy continues. Set CONVOX_ENV_DROP_GUARD=strict to make the guard blocking instead. Passing --force reduces the warning to a one-line notice and bypasses the guard in strict mode, in addition to its existing meaning of promoting without waiting for readiness.

External Builds

The --external flag runs the Docker build locally instead of uploading the source to the rack. convox deploy --external uses the same flow as convox build --external and additionally promotes the resulting Release.

    $ convox deploy --external -a myapp

See build: External Builds for the flow, requirements, and example output.

Failure Messages

When a rollout fails, convox deploy names the App and the command to run next:

    ERROR: rollout failed for myapp, the previous release was restored
      convox deploy-debug -a myapp

If the command reaches its own 35-minute ceiling while the Rack is still rolling out, it reports that instead. The Rack continues past the CLI ceiling, so the Release still finishes or still rolls back without the command watching.

    ERROR: myapp did not reach a running state within 35m, the rack may still be rolling out
      convox deploy-debug -a myapp
      convox apps cancel -a myapp

See Rolling Updates: Failure Detection for the settings that make a broken rollout fail in minutes instead of after the 50-minute default.

See Also

• Deploying Changes for deployment workflow
• Rolling Updates for deployment strategies
• deploy-debug for diagnosing failed deployments