Skip to content

[Containers] Document Docker Hub image support #29092

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
nikitassharma wants to merge 3 commits into
base: production
Choose a base branch
from
Open

[Containers] Document Docker Hub image support #29092

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7d72a90
[Containers] Document Docker Hub image support
nikitassharma Mar 18, 2026
6f9a363
[Containers] Add Docker Hub changelog entry
nikitassharma Mar 18, 2026
e026cc8
pr feedback
nikitassharma Mar 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 31 additions & 0 deletions src/content/changelog/containers/2026-03-18-docker-hub-images.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
---
title: Use Docker Hub images with Containers
description: Pull public or private Docker Hub images in Containers.
products:
- containers
date: 2026-03-18
Copy link
Contributor

@mikenomitch mikenomitch Mar 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note: date needs updating

---

import { WranglerConfig } from "~/components";

[Containers](/containers/) now support pulling public Docker Hub images directly from the `image` field. This lets you deploy a pre-built image without first pushing it to the Cloudflare Registry.
Copy link
Contributor

@mikenomitch mikenomitch Mar 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"pulling public Docker Hub images directly from the image field"

Sounds like we're pulling from the field itself, I'd reword slightly


To use a public image, set `image` to a fully qualified Docker Hub image reference:

<WranglerConfig>

```jsonc
{
"containers": [
{
"image": "docker.io/<NAMESPACE>/<REPOSITORY>:<TAG>",
Copy link
Contributor

@mikenomitch mikenomitch Mar 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd add a comment with a real one above so people can pattern match here?

Copy link
Member Author

@nikitassharma nikitassharma Mar 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

pulled the image from the sandbox template

@ghostwriternr can you confirm if this is okay to include as the example?

},
],
}
```

</WranglerConfig>

You can also use private Docker Hub images after you configure `docker.io` with `wrangler containers registries configure`. Docker Hub images are not cached, so pulls may be subject to Docker Hub pull limits or fair-use restrictions.
Copy link
Contributor

@mikenomitch mikenomitch Mar 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would link to the wrangler command docs - https://developers.cloudflare.com/workers/wrangler/commands/containers/#containers-registries-configure

and I'd say "not yet cached" since it'll come eventually (right? - if not, then nvm)

Copy link
Contributor

@mikenomitch mikenomitch Mar 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually, I'd link to the docs where you explain how to do this


For more information, refer to [Image management](/containers/platform-details/image-management/).
2 changes: 1 addition & 1 deletion src/content/docs/containers/faq.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -85,7 +85,7 @@ on image size and code execution time, among other factors.

## How do I use an existing container image?

See [image management documentation](/containers/platform-details/image-management/#using-existing-images) for details.
See [image management documentation](/containers/platform-details/image-management/#use-pre-built-container-images) for details.

## Is disk persistent? What happens to my disk when my container sleeps?

Expand Down
22 changes: 10 additions & 12 deletions src/content/docs/containers/get-started.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ And see images deployed to the Cloudflare Registry with the following command:

### Make requests to Containers

Now, open the URL for your Worker. It should look something like `https://hello-containers.YOUR_ACCOUNT_NAME.workers.dev`.
Now, open the URL for your Worker. It should look something like `https://hello-containers.<YOUR_WORKERS_SUBDOMAIN>.workers.dev`.

If you make requests to the paths `/container/1` or `/container/2`, your Worker routes requests to specific containers.
Each different path after "/container/" routes to a unique container.
Expand Down Expand Up @@ -113,33 +113,31 @@ Your [Wrangler configuration file](/workers/wrangler/configuration/) defines the
{
"max_instances": 10,
"class_name": "MyContainer",
"image": "./Dockerfile"
}
"image": "./Dockerfile",
},
],
"durable_objects": {
"bindings": [
{
"name": "MY_CONTAINER",
"class_name": "MyContainer"
}
]
"class_name": "MyContainer",
},
],
},
"migrations": [
{
"tag": "v1",
"new_sqlite_classes": [
"MyContainer"
]
}
]
"new_sqlite_classes": ["MyContainer"],
},
],
}
```

</WranglerConfig>

Important points about this config:

- `image` points to a Dockerfile or to a directory containing a Dockerfile.
- `image` points to a Dockerfile, to a directory containing a Dockerfile, or to a fully qualified image reference such as `registry.cloudflare.com/<YOUR_ACCOUNT_ID>/<IMAGE>:<TAG>`.
- `class_name` must be a [Durable Object class name](/durable-objects/api/base/).
- `max_instances` declares the maximum number of simultaneously running container instances
that will run.
Expand Down
14 changes: 10 additions & 4 deletions src/content/docs/containers/local-dev.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
---
pcx_content_type: reference
title: Local Development
description: Learn how to run Container-enabled Workers locally with `wrangler dev` and `vite dev`.
sidebar:
order: 6
---
Expand All @@ -13,11 +14,16 @@ Docker compatible CLI tool and Engine are installed. For instance, you could use
When you start a dev session, your container image will be built or downloaded. If your
[Wrangler configuration](/workers/wrangler/configuration/#containers) sets
the `image` attribute to a local path, the image will be built using the local Dockerfile.
If the `image` attribute is set to a URL, the image will be pulled from the Cloudflare registry.
If the `image` attribute is set to an image reference, the image will be pulled from the referenced registry, such as the Cloudflare Registry, Docker Hub, or Amazon ECR.

:::note
Currently, the Cloudflare Vite-plugin does not support registry links in local development, unlike `wrangler dev`.
As a workaround, you can create a minimal Dockerfile that uses `FROM <registry-link>`. Make sure to `EXPOSE` a port for local dev as well.
With `wrangler dev`, image references from the Cloudflare Registry, Docker Hub, and Amazon ECR are supported in local development.

With `vite dev`, image references from external registries such as Docker Hub and Amazon ECR are supported, but `vite dev` cannot pull directly from the Cloudflare Registry.

If you use a private Docker Hub or ECR image with `vite dev`, authenticate to that registry locally, for example with `docker login`.

As a workaround for Cloudflare Registry images, point `vite dev` at a local Dockerfile that uses `FROM <IMAGE_REFERENCE>`. Docker then pulls the base image during the local build. Make sure to `EXPOSE` a port for local dev as well.
:::

Container instances will be launched locally when your Worker code calls to create
Expand Down Expand Up @@ -98,4 +104,4 @@ To resolve this, you can either:
This snippet will store the certificate into the image. Depending on whether your production environment needs the certificate, you may choose to do this only during development or use it in production too.
:::

Wrangler invokes Docker automatically when you run `wrangler dev` or `wrangler deploy`, so if you need to pass build secrets, you will need to build and push the image manually using `wrangler containers images push`.
Wrangler invokes Docker automatically when you run `wrangler dev` or `wrangler deploy`, so if you need to pass build secrets, you will need to build and push the image manually using `wrangler containers push`.
Loading
Loading