Automatically get docker socket path (and fix socket path config in vite plugin) #10061

emily-shen · 2025-07-24T16:00:36Z

Fixes DEVX-2103.

Uses docker context ls to get the socket path that the docker daemon is listening on, without having to manually set it via config or an env var. This is he

Also checks the env var DOCKER_HOST (in addition to WRANGLER_DOCKER_HOST), which is a standard.

Also sets this properly in the vite plugin - we were previously only picking up the value set in the wrangler config.

This has unit tests but i've also tested this manually with the vite plugin/wrangler dev and colima (which listens at a special colima socket).

Tests
- Tests included
- Tests not necessary because:
Public documentation
- Cloudflare docs PR(s): update containers local dev socket configuration docs cloudflare-docs#23963
- Documentation not necessary because:
Wrangler V3 Backport
- Wrangler PR:
- Not necessary because: new feature

changeset-bot · 2025-07-24T16:00:40Z

🦋 Changeset detected

Latest commit: 95c381a

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages

Name	Type
@cloudflare/containers-shared	Patch
wrangler	Patch
@cloudflare/vite-plugin	Patch
@cloudflare/vitest-pool-workers	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

github-actions · 2025-07-24T16:01:55Z

Failed to automatically backport this PR's changes to Wrangler v3. Please manually create a PR targeting the v3-maintenance branch with your changes. Thank you for helping us keep Wrangler v3 supported!

Depending on your changes, running git rebase --onto v3-maintenance main emily/find-socket-docker-context might be a good starting point.

Notes:

your PR branch should be named v3-backport-10061
add the skip-v3-pr label to the current PR to stop this workflow from failing

pkg-pr-new · 2025-07-24T16:03:02Z

create-cloudflare

npm i https://pkg.pr.new/create-cloudflare@10061

@cloudflare/kv-asset-handler

npm i https://pkg.pr.new/@cloudflare/kv-asset-handler@10061

miniflare

npm i https://pkg.pr.new/miniflare@10061

@cloudflare/pages-shared

npm i https://pkg.pr.new/@cloudflare/pages-shared@10061

@cloudflare/unenv-preset

npm i https://pkg.pr.new/@cloudflare/unenv-preset@10061

@cloudflare/vite-plugin

npm i https://pkg.pr.new/@cloudflare/vite-plugin@10061

@cloudflare/vitest-pool-workers

npm i https://pkg.pr.new/@cloudflare/vitest-pool-workers@10061

@cloudflare/workers-editor-shared

npm i https://pkg.pr.new/@cloudflare/workers-editor-shared@10061

wrangler

npm i https://pkg.pr.new/wrangler@10061

commit: 95c381a

vicb

LGTM,

Added some inline comments

vicb · 2025-07-24T17:02:01Z

.changeset/full-pugs-say.md

+"wrangler": patch
+---
+
+feat: try to automatically get path of docker socket


A few questions:

Should "feat" imply a minor release?

Should "docker socket" be "container engine socket" (and use "container engine" below and in the other changeset rather than "docker" or "container tool")

our general rule of thumb apparently is features on experimental products get releases as patches, so i'll probably keep this as is.

good point on the docker specific language, i'll update the changesets

.changeset/full-pugs-say.md

vicb · 2025-07-24T17:05:14Z

.changeset/full-pugs-say.md

+
+Currently, if your container tool isn't set up to listen at `unix:///var/run/docker.sock` (or isn't symlinked to that), then you have to manually set this via the `dev.containerEngine` field in your Wrangler config, or via the env vars `WRANGLER_DOCKER_HOST`. This change means that we will try and get the socket of the current context automatically. This should reduce the occurrence of opaque `internal error`s thrown by the runtime when the daemon is not listening at `unix:///var/run/docker.sock`.
+
+You can still override this with `WRANGLER_DOCKER_HOST`, and we also now read `DOCKER_HOST` too.


Suggested change

You can still override this with `WRANGLER_DOCKER_HOST`, and we also now read `DOCKER_HOST` too.

In addition to `WRANGLER_DOCKER_HOST`, `DOCKER_HOST` can now also be used to set the container engine socket address.

vicb · 2025-07-24T17:07:16Z

packages/containers-shared/src/utils.ts

-			return resolve(stdout.trim());
-		});
-	});
+export const runDockerCmdWithOutput = (dockerPath: string, args: string[]) => {


Out of curiosity what what this changed from async to sync? (not mentioned in the PR description).

Does it deserves a comment explaining why it should not be async?

the unstable_getMiniflareWorkerOptions api needs to use this to resolve the socket path, and that function is sync (and part of wranglers public api surface) so i wanted to avoid changing that.

vicb · 2025-07-24T17:10:04Z

packages/containers-shared/src/utils.ts

 	return randomUUID().slice(0, 8);
 }
+
+type DockerContext = {


Looks like this is parsed from docker context ls, maybe add a comment.

Would it be worth adding some validations (zod or whatever) on top of JSON.parse

i don't really want to add zod just to validate this one thing, if it fails we have a sensible fallback. i mean, i would love to add zod to validate very many things across wrangler, but this probably isn't the place to start 😅

but comment added though :)

packages/containers-shared/tests/docker-context.test.ts

vicb · 2025-07-24T17:44:23Z

packages/wrangler/src/api/dev.ts

+		dockerPath,
+		containerEngine: options?.experimental?.containerEngine,


It looks like the diff on the first line is only moving code around.

Is the second line diff expected ?

yep - i don't want to try and get the socket path unless we are sure there are containers configured and enableContainers is true, but i don't think we have read the config yet here so we can't do that. instead i set it later on in configController.

packages/wrangler/src/environment-variables/misc-variables.ts

try to get docker socket from docker context ls

906780d

emily-shen requested review from a team as code owners July 24, 2025 16:00

workers-devprod added this to workers-sdk Jul 24, 2025

github-project-automation bot moved this to Untriaged in workers-sdk Jul 24, 2025

emily-shen added 3 commits July 24, 2025 17:18

changeset

d784193

fix socket config in vite plugin

4fd776d

only test in ci on linux

7c37a6e

emily-shen force-pushed the emily/find-socket-docker-context branch from 974cf07 to 7c37a6e Compare July 24, 2025 16:18

vicb approved these changes Jul 24, 2025

View reviewed changes

github-project-automation bot moved this from Untriaged to Approved in workers-sdk Jul 24, 2025

PR feedback

95c381a

emily-shen added the skip-v3-pr Skip validation of presence of a v3 backport PR label Jul 25, 2025

emily-shen mentioned this pull request Jul 25, 2025

update containers local dev socket configuration docs cloudflare/cloudflare-docs#23963

Merged

emily-shen merged commit f8a80a8 into main Jul 25, 2025
49 of 55 checks passed

emily-shen deleted the emily/find-socket-docker-context branch July 25, 2025 13:39

github-project-automation bot moved this from Approved to Done in workers-sdk Jul 25, 2025

workers-devprod mentioned this pull request Jul 25, 2025

Version Packages #10059

Merged

emily-shen mentioned this pull request Jul 28, 2025

recommend DOCKER_HOST instead #10097

Merged

6 tasks


		Currently, if your container tool isn't set up to listen at `unix:///var/run/docker.sock` (or isn't symlinked to that), then you have to manually set this via the `dev.containerEngine` field in your Wrangler config, or via the env vars `WRANGLER_DOCKER_HOST`. This change means that we will try and get the socket of the current context automatically. This should reduce the occurrence of opaque `internal error`s thrown by the runtime when the daemon is not listening at `unix:///var/run/docker.sock`.

		You can still override this with `WRANGLER_DOCKER_HOST`, and we also now read `DOCKER_HOST` too.

	You can still override this with `WRANGLER_DOCKER_HOST`, and we also now read `DOCKER_HOST` too.
	In addition to `WRANGLER_DOCKER_HOST`, `DOCKER_HOST` can now also be used to set the container engine socket address.

		dockerPath,
		containerEngine: options?.experimental?.containerEngine,

Automatically get docker socket path (and fix socket path config in vite plugin) #10061

Automatically get docker socket path (and fix socket path config in vite plugin) #10061

Uh oh!

Conversation

emily-shen commented Jul 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot bot commented Jul 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

github-actions bot commented Jul 24, 2025

Uh oh!

pkg-pr-new bot commented Jul 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vicb left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

emily-shen Jul 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

emily-shen commented Jul 24, 2025 •

edited

Loading

changeset-bot bot commented Jul 24, 2025 •

edited

Loading

pkg-pr-new bot commented Jul 24, 2025 •

edited

Loading

emily-shen Jul 25, 2025 •

edited

Loading