Skip to content

Deploy Containers

Last updated View as MarkdownAgent setup

Deploy from your machine

  1. If image in your Wrangler config is a path to a Dockerfile, start Docker ↗ or another Docker-compatible engine. Specify the Dockerfile itself, not its directory. If image is a registry reference (Cloudflare Registry, Docker Hub, Amazon ECR, or Google Artifact Registry), you do not need Docker at deploy time. Refer to Image management.

  2. From your project directory, run:

    npx wrangler deploy

  3. Wait for the command to finish.

wrangler deploy uploads and activates your Worker before it processes the container configuration. For a Dockerfile image, Wrangler then builds and pushes the image when needed. For a registry image, it uses the configured image reference. These steps are not transactional: an image build, image push, or rollout error can happen after the new Worker is already live.

For an existing container application, Wrangler starts a rollout when the effective container configuration changes. The command does not wait for every container instance to be replaced, so new Worker code may briefly talk to containers that still run the previous image. The first deploy creates the container application directly, and a deploy with no effective container changes starts no rollout.

For rollout flags and step configuration, refer to Rollouts.

Deploy with Workers Builds

Workers Builds runs the build and deploy commands you configure for the Worker that is connected to your Git repository.

Git branch Default deploy command Containers
Production branch npx wrangler deploy Publishes the image when needed and rolls out container instances. Dockerfile builds can run in the Workers Builds environment.
Other branches (if non-production branch builds are enabled) npx wrangler versions upload Uploads Worker code only. Does not publish a new image or roll out container instances.

Production

  1. In the Cloudflare dashboard, go to Workers & Pages, open the Worker you want to deploy, then go to Settings > Builds.

    Go to Workers & Pages ↗

  2. Set Deploy command to npx wrangler deploy, or to a package script that runs a full deploy.

  3. Keep your Wrangler config and Dockerfile or image reference under the Workers Builds root directory.

  4. Push to your production branch.

  5. Confirm the build succeeds, then check the deploy.

To connect a repository, refer to Workers Builds.

Before production

  • wrangler deploy publishes container images (when needed) and rolls out container instances for the Worker you deploy.
  • wrangler versions upload (the default non-production branch deploy command in Workers Builds) uploads a new Worker version only. It does not publish a new image or roll out container instances.
  • Preview URLs are not generated for Workers that implement Durable Objects, which includes Containers Workers. A successful non-production Workers Builds run still creates a Worker version, but not a full-app preview URL.
Goal What to do
Change Worker and container together on your machine Local development with wrangler dev
Share a deployed environment with its own image and container instances A Wrangler environment or a separate Worker, each connected to Workers Builds with a full deploy command such as npx wrangler deploy --env staging. Refer to Workers Builds and Wrangler environments.
Update production Merge to the production branch (or run wrangler deploy locally)

Check your deploy

After wrangler deploy or a production Workers Builds deploy:

  1. Confirm the new Worker deployment is active in the dashboard.

  2. Send a request that must reach the container and confirm the behavior you expect.

  3. Optionally run npx wrangler containers list and npx wrangler containers images list, or open the Containers dashboard:

    Go to Containers ↗

For gradual steps, grace periods, and rollout modes, refer to Rollouts.

Troubleshooting

Problem What to do
Non-production Workers Builds run succeeds but you cannot fully preview the app Use local development or a staging Worker or environment with wrangler deploy. Refer to Before production.
Deploy or Workers Builds run succeeds but container instances look unchanged A gradual rollout may still be running, or the command did not update containers (versions upload or --containers-rollout=none). Refer to Rollouts.
Deploy fails because Docker is missing Required only when image is a Dockerfile path. Start Docker, use Workers Builds, switch to a registry image, or use --containers-rollout=none for a Worker-only deploy.
First deploy: Worker works, container routes error Wait several minutes for provisioning, then check logs.

Was this helpful?