In this guide, you will deploy a Worker that can make requests to one or more Containers in response to end-user requests. In this example, each container runs a small webserver written in Go.
This example Worker should give you a sense for simple Container use, and provide a starting point for more complex use cases.
This guide uses the Durable Object Container API. A Durable Object starts its container through ctx.container and forwards requests to it.
In this guide, we will build and push a container image alongside your Worker code. By default, this process uses Docker ↗︎ to do so.
You must have Docker running locally when you run wrangler deploy. For most people, the best way to install Docker is to follow the docs for installing Docker Desktop ↗︎. Other tools like Colima ↗︎ may also work.
You can check that Docker is running properly by running the docker info command in your terminal. If Docker is running, the command will succeed. If Docker is not running,
the docker info command will hang or return an error including the message "Cannot connect to the Docker daemon".
Run the following command to create and deploy a new Worker with a container, from the starter template:
npm create cloudflare@latest -- --template=cloudflare/templates/containers-templateyarn create cloudflare --template=cloudflare/templates/containers-templatepnpm create cloudflare@latest --template=cloudflare/templates/containers-templateWhen you want to deploy a code change to either the Worker or Container code, you can run the following command using Wrangler CLI:
npx wrangler deployyarn wrangler deploypnpm wrangler deployOn deploy, Wrangler uploads your Worker, builds and pushes the container image with Docker, and updates container instances on Cloudflare's network. The first build and push usually take the longest. Later deploys reuse cached image layers ↗︎.
After deploying, list containers in your account and their status:
npx wrangler containers listyarn wrangler containers listpnpm wrangler containers listList images in the Cloudflare Registry:
npx wrangler containers images listyarn wrangler containers images listpnpm wrangler containers images listOpen the URL for your Worker. It should look like https://hello-containers.<YOUR_WORKERS_SUBDOMAIN>.workers.dev.
- Requests to
/container/1or/container/2route to specific containers. Each path after/container/maps to a unique container. - Requests to
/lbload-balance across three containers chosen at random. - Requests to
/singletonalways route to the same container. - Requests to
/errormake a dedicated test container exit with an error.
Read the response body to confirm which instance handled the request. If the Worker responds but container routes still error, wait for provisioning, then check Containers ↗︎ logs in the dashboard.
Now that you've deployed your first container, let's explain what is happening in your Worker's code, in your configuration file, in your container's code, and how requests are routed.
Your Wrangler configuration file defines the configuration for both your Worker and your container:
{
"containers": [
{
"class_name": "MyContainer",
"scheduling_policy": "durable_object",
"images": {
"base": {
"dockerfile": "./Dockerfile",
},
},
},
],
"durable_objects": {
"bindings": [
{
"name": "MY_CONTAINER",
"class_name": "MyContainer",
},
],
},
"exports": {
"MyContainer": {
"type": "durable-object",
"storage": "sqlite",
},
},
}[[containers]]
class_name = "MyContainer"
scheduling_policy = "durable_object"
[containers.images.base]
dockerfile = "./Dockerfile"
[[durable_objects.bindings]]
name = "MY_CONTAINER"
class_name = "MyContainer"
[exports.MyContainer]
type = "durable-object"
storage = "sqlite"Important points about this config:
class_namemust be a Durable Object class name.scheduling_policyisdurable_object, so the Durable Object chooses the image and instance type each time it starts a container. Refer to Scheduling policy.images.basenames an image that Wrangler builds from the Dockerfile. The Durable Object passes it tostart()asctx.container.images.base.- The
exportsentry declares the Durable Object class with SQLite storage. Existing applications that use the legacymigrationsarray can continue to use it, butexportsandmigrationscannot be combined.
Your container image must be able to run on the linux/amd64 architecture, but aside from that, has few limitations.
In the example you just deployed, it is a simple Golang server that responds to requests on port 8080 using
the MESSAGE and INSTANCE_ID environment variables that the Durable Object passes when it starts the container. It also answers /health so the Durable Object can check that the server is ready.
func handler(w http.ResponseWriter, r *http.Request) {
message := os.Getenv("MESSAGE")
instanceId := os.Getenv("INSTANCE_ID")
fmt.Fprintf(w, "Hi, I'm a container and this is my message: \"%s\", my instance ID is: %s", message, instanceId)
}MyContainer extends DurableObject. It starts its container on the first request, waits for the container's HTTP server, and forwards requests to it:
const PORT = 8080;
const INACTIVITY_TIMEOUT_MS = 2 * 60 * 1000;
export class MyContainer extends DurableObject<Env> {
private starting: Promise<void> | undefined;
private monitoring: Promise<void> | undefined;
constructor(ctx: DurableObjectState, env: Env) {
super(ctx, env);
const container = ctx.container;
if (container?.running) {
// Restore the timeout and exit monitoring after a DO restart.
void ctx.blockConcurrencyWhile(() =>
container.setInactivityTimeout(INACTIVITY_TIMEOUT_MS),
);
this.observeExit();
}
}
async fetch(request: Request): Promise<Response> {
// Share startup across concurrent requests, including after a failed attempt.
this.starting ??= this.startAndWaitForPort().finally(() => {
this.starting = undefined;
});
await this.starting;
const url = new URL(request.url);
url.protocol = "http:";
url.host = "container";
const forwarded = new Request(url, request);
forwarded.headers.delete("host");
return this.ctx.container!.getTcpPort(PORT).fetch(forwarded);
}
private async startAndWaitForPort(): Promise<void> {
const container = this.ctx.container!;
if (!container.running) {
container.start({
image: container.images.base,
instance: "lite",
enableInternet: false,
env: {
MESSAGE: "I was passed in when the Durable Object started me!",
INSTANCE_ID: this.ctx.id.toString(),
},
});
}
this.observeExit();
await container.setInactivityTimeout(INACTIVITY_TIMEOUT_MS);
// running means startup was requested, not that the HTTP server is ready.
const port = container.getTcpPort(PORT);
for (let attempt = 0; attempt < 100; attempt++) {
try {
const response = await port.fetch("http://container/health", {
signal: AbortSignal.timeout(1000),
});
await response.body?.cancel();
if (response.ok) return;
} catch {
// The port may not be listening yet. Retry the readiness probe only.
}
await scheduler.wait(200);
}
throw new Error("Container did not become ready on port 8080");
}
private observeExit(): void {
if (this.monitoring) return;
this.monitoring = this.ctx
.container!.monitor()
.then(() => console.log("Container exited successfully"))
.catch((error: unknown) => console.error("Container failed:", error))
.finally(() => {
this.monitoring = undefined;
});
this.ctx.waitUntil(this.monitoring);
}
}This code does the following:
start()boots the container with thebaseimage, theliteinstance type, no Internet access, and two environment variables. It returns before the container is ready.- The readiness loop sends requests to
/healththroughgetTcpPort()until the server answers. setInactivityTimeout()keeps the container running for two minutes after the Durable Object becomes inactive. The constructor sets the timeout again when the Durable Object restarts while its container runs.getTcpPort(PORT).fetch()forwards each request to the container.monitor()logs when the container exits. On the/errorroute, the container exits with code1, andmonitor()rejects with the error.
Because MyContainer is a Durable Object, it has access to the full Durable Object API. The Durable Object handles routing, lifecycle, and persistent state, while the container process runs your image inside a Linux VM. This means you can use this.ctx.storage to persist data that survives container restarts and resides close to the container itself.
For all properties and methods, refer to the Durable Object Container API.
When a request enters Cloudflare, your Worker's fetch handler is invoked. This is the code that handles the incoming request. The example code uses the Hono ↗︎ framework to route requests. It launches containers in two ways, on different routes:
-
Making requests to
/container/passes requests to a new container for each path. This is done by spinning up a new Container instance. You may note that the first request to a new path takes longer than subsequent requests, this is because a new container is booting.app.get("/container/:id", (c) => c.env.MY_CONTAINER.getByName(`/container/${c.req.param("id")}`).fetch( c.req.raw, ), ); -
Making requests to
/lbwill load balance requests across several containers. The Worker picks a name at random from a fixed pool (in this case three), then routes to that Container instance. You can replace this with any routing or load balancing logic you choose to implement:const POOL_SIZE = 3; app.get("/lb", (c) => { const index = Math.floor(Math.random() * POOL_SIZE); return c.env.MY_CONTAINER.getByName(`pool-${index}`).fetch(c.req.raw); });
This allows for multiple ways of using Containers:
- If you simply want to send requests to many stateless and interchangeable containers, you should load balance.
- If you have stateful services or need individually addressable containers, you should request specific Container instances.
- If you are running short-lived jobs, want fine-grained control over the container lifecycle, want to parameterize container entrypoint or env vars, or want to chain together multiple container calls, you should request specific Container instances.
The Containers Dashboard ↗︎ shows you helpful information about your Containers, including:
- Status and Health
- Metrics
- Logs
After launching your Worker, go to the Containers Dashboard by selecting Workers & Pages > Containers in the dashboard sidebar.
To do more:
- Modify the image by changing the Dockerfile and running
wrangler deploy - Refer to Deploy Containers for Workers Builds and rollout behavior
- Browse examples for more patterns
- Check the Frequently Asked Questions for platform behavior and limitations