Skip to content

[containers] Update local-dev.mdx #24598

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

Closed
wants to merge 1 commit into from
Closed

[containers] Update local-dev.mdx #24598

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
32 changes: 31 additions & 1 deletion src/content/docs/containers/local-dev.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,32 @@ sidebar:
order: 3
---

You can run both your container and your Worker locally, without additional configuration, by running [`npx wrangler dev`](/workers/wrangler/commands/#dev) (or `vite dev` for Vite projects using the [Cloudflare Vite plugin](/workers/vite-plugin/)) in your project's directory.
You can run both your container and your Worker locally by running [`npx wrangler dev`](/workers/wrangler/commands/#dev) (or `vite dev` for Vite projects using the [Cloudflare Vite plugin](/workers/vite-plugin/)) in your project's directory.

To develop Container-enabled Workers locally, you will need to first ensure that a
Docker compatible CLI tool and Engine are installed. For instance, you could use [Docker Desktop](https://docs.docker.com/desktop/) or [Colima](https://github.com/abiosoft/colima).

## Required Configuration

For local development, your `wrangler.json` or `wrangler.jsonc` file must include specific configuration fields:

```json
{
"containers": [{
"name": "your-container-name", // Required for local development
"class_name": "YourContainerClass", // Your Durable Object class name
"image": "./path/to/Dockerfile", // Path to your Dockerfile
"instance_type": "standard", // Required for proper runtime behavior
"max_instances": 2 // Optional, not enforced locally
}],
"compatibility_flags": ["nodejs_compat"] // Required when using Container class from @cloudflare/containers
}
```

:::note
The `name` and `instance_type` fields are essential for local development. Without them, you may encounter "Connection refused: container port not found" errors even if your container is properly configured.
:::

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.
Expand Down Expand Up @@ -46,6 +67,15 @@ you are using in your container code.

## Troubleshooting

### Container Configuration Errors

If you encounter "Connection refused: container port not found" errors during local development, verify that:

1. Your container configuration includes a `name` field
2. Your container configuration includes an `instance_type` field (typically `"standard"`)
3. You have `nodejs_compat` in your `compatibility_flags` array if using the Container class from `@cloudflare/containers`
4. Your Dockerfile includes the necessary `EXPOSE` instructions (see below)

### Exposing Ports

In production, all of your container's ports will be accessible by your Worker, so you do not need to specifically expose ports using the [`EXPOSE` instruction](https://docs.docker.com/reference/dockerfile/#expose) in your Dockerfile.
Expand Down