sync local containers with latest workerd (#9576)

vicb · emily-shen · web-flow · commit 2671e778435b · 2025-06-17T16:15:57.000Z
Co-authored-by: emily-shen &lt;69125074+emily-shen@users.noreply.github.com&gt;
diff --git a/.changeset/weak-months-speak.md b/.changeset/weak-months-speak.md
@@ -0,0 +1,7 @@
+---
+"miniflare": patch
+"wrangler": patch
+---
+
+Add core local dev functionality for containers.
+Adds a new WRANGLER_DOCKER_HOST env var to customise what socket to connect to.
diff --git a/packages/miniflare/src/index.ts b/packages/miniflare/src/index.ts
@@ -344,6 +344,7 @@ function getDurableObjectClassNames(
 				enableSql,
 				unsafeUniqueKey,
 				unsafePreventEviction,
+				container,
 			} = normaliseDurableObject(designator);
 			// Get or create `Map` mapping class name to optional unsafe unique key
 			let classNames = serviceClassNames.get(serviceName);
@@ -385,6 +386,7 @@ function getDurableObjectClassNames(
 					enableSql,
 					unsafeUniqueKey,
 					unsafePreventEviction,
+					container,
 				});
 			}
 		}
diff --git a/packages/miniflare/src/plugins/containers/service/index.ts b/packages/miniflare/src/plugins/containers/service/index.ts
@@ -26,6 +26,11 @@ export class ContainerController {
 		this.#containerOptions = containerOptions;
 		this.#sharedOptions = sharedOptions;
 		this.#logger = logger;
+		if (process.platform === "win32") {
+			throw new Error(
+				"Local development with containers is currently not supported on Windows. You should use WSL instead. You can also set `enable_containers` to false if you do not need to develop the container part of your application."
+			);
+		}
 	}
 
 	updateConfig(
diff --git a/packages/miniflare/src/plugins/core/index.ts b/packages/miniflare/src/plugins/core/index.ts
@@ -1,6 +1,7 @@
 import assert from "assert";
 import { readFileSync } from "fs";
 import fs from "fs/promises";
+import { platform } from "node:os";
 import path from "path";
 import { Readable } from "stream";
 import tls from "tls";
@@ -18,6 +19,7 @@ import {
 	ServiceDesignator,
 	supportedCompatibilityDate,
 	Worker_Binding,
+	Worker_ContainerEngine,
 	Worker_DurableObjectNamespace,
 	Worker_Module,
 } from "../../runtime";
@@ -166,6 +168,16 @@ const CoreOptionsSchemaInput = z.intersection(
 
 		// Strip the CF-Connecting-IP header from outbound fetches
 		stripCfConnectingIp: z.boolean().default(true),
+
+		/** Configuration used to connect to the container engine */
+		containerEngine: z
+			.union([
+				z.object({
+					localDocker: z.object({ socketPath: z.string() }),
+				}),
+				z.string(),
+			])
+			.optional(),
 	})
 );
 export const CoreOptionsSchema = CoreOptionsSchemaInput.transform((value) => {
@@ -736,28 +748,32 @@ export const CORE_PLUGIN: Plugin<
 						classNamesEntries.map<Worker_DurableObjectNamespace>(
 							([
 								className,
-								{ enableSql, unsafeUniqueKey, unsafePreventEviction },
-							]) => {
-								if (unsafeUniqueKey === kUnsafeEphemeralUniqueKey) {
-									return {
-										className,
-										enableSql,
-										ephemeralLocal: kVoid,
-										preventEviction: unsafePreventEviction,
-									};
-								} else {
-									return {
-										className,
-										enableSql,
-										// This `uniqueKey` will (among other things) be used as part of the
-										// path when persisting to the file-system. `-` is invalid in
-										// JavaScript class names, but safe on filesystems (incl. Windows).
-										uniqueKey:
-											unsafeUniqueKey ?? `${options.name ?? ""}-${className}`,
-										preventEviction: unsafePreventEviction,
-									};
-								}
-							}
+								{
+									enableSql,
+									unsafeUniqueKey,
+									unsafePreventEviction: preventEviction,
+									container,
+								},
+							]) =>
+								unsafeUniqueKey === kUnsafeEphemeralUniqueKey
+									? {
+											className,
+											enableSql,
+											ephemeralLocal: kVoid,
+											preventEviction,
+											container,
+										}
+									: {
+											className,
+											enableSql,
+											// This `uniqueKey` will (among other things) be used as part of the
+											// path when persisting to the file-system. `-` is invalid in
+											// JavaScript class names, but safe on filesystems (incl. Windows).
+											uniqueKey:
+												unsafeUniqueKey ?? `${options.name ?? ""}-${className}`,
+											preventEviction,
+											container,
+										}
 						),
 					durableObjectStorage:
 						classNamesEntries.length === 0
@@ -787,6 +803,7 @@ export const CORE_PLUGIN: Plugin<
 										options.hasAssetsAndIsVitest
 									);
 								}),
+					containerEngine: getContainerEngine(options.containerEngine),
 				},
 			});
 		}
@@ -1022,6 +1039,29 @@ function getWorkerScript(
 	}
 }
 
+/**
+ * Returns the Container engine configuration
+ * @param engineOrSocketPath Either a full engine config or a unix socket
+ * @returns The container engine, default to local Docker at `unix:/var/run/docker.sock`
+ */
+function getContainerEngine(
+	engineOrSocketPath: Worker_ContainerEngine | string | undefined
+): Worker_ContainerEngine {
+	if (!engineOrSocketPath) {
+		// TODO: workerd does not support win named pipes
+		engineOrSocketPath =
+			platform() === "win32"
+				? "//./pipe/docker_engine"
+				: "unix:/var/run/docker.sock";
+	}
+
+	if (typeof engineOrSocketPath === "string") {
+		return { localDocker: { socketPath: engineOrSocketPath } };
+	}
+
+	return engineOrSocketPath;
+}
+
 export * from "./errors";
 export * from "./proxy";
 export * from "./constants";
diff --git a/packages/miniflare/src/plugins/do/index.ts b/packages/miniflare/src/plugins/do/index.ts
@@ -12,6 +12,12 @@ import {
 	UnsafeUniqueKey,
 } from "../shared";
 
+// Options for a container attached to the DO
+export const DOContainerOptionsSchema = z.object({
+	imageName: z.string(),
+});
+export type DOContainerOptions = z.infer<typeof DOContainerOptionsSchema>;
+
 export const DurableObjectsOptionsSchema = z.object({
 	durableObjects: z
 		.record(
@@ -33,6 +39,7 @@ export const DurableObjectsOptionsSchema = z.object({
 					mixedModeConnectionString: z
 						.custom<MixedModeConnectionString>()
 						.optional(),
+					container: z.custom<DOContainerOptions>().optional(),
 				}),
 			])
 		)
@@ -54,6 +61,7 @@ export function normaliseDurableObject(
 	unsafeUniqueKey: UnsafeUniqueKey | undefined;
 	unsafePreventEviction: boolean | undefined;
 	mixedModeConnectionString: MixedModeConnectionString | undefined;
+	container: DOContainerOptions | undefined;
 } {
 	const isObject = typeof designator === "object";
 	const className = isObject ? designator.className : designator;
@@ -70,6 +78,7 @@ export function normaliseDurableObject(
 	const mixedModeConnectionString = isObject
 		? designator.mixedModeConnectionString
 		: undefined;
+	const container = isObject ? designator.container : undefined;
 	return {
 		className,
 		scriptName,
@@ -78,6 +87,7 @@ export function normaliseDurableObject(
 		unsafeUniqueKey,
 		unsafePreventEviction,
 		mixedModeConnectionString,
+		container,
 	};
 }
 
diff --git a/packages/miniflare/src/plugins/shared/index.ts b/packages/miniflare/src/plugins/shared/index.ts
@@ -23,6 +23,7 @@ import {
 	sanitisePath,
 } from "../../workers";
 import { UnsafeUniqueKey } from "./constants";
+import type { DOContainerOptions } from "../do";
 
 export const DEFAULT_PERSIST_ROOT = ".mf";
 
@@ -47,6 +48,7 @@ export type DurableObjectClassNames = Map<
 			enableSql?: boolean;
 			unsafeUniqueKey?: UnsafeUniqueKey;
 			unsafePreventEviction?: boolean;
+			container?: DOContainerOptions;
 		}
 	>
 >;
diff --git a/packages/miniflare/src/runtime/config/workerd.ts b/packages/miniflare/src/runtime/config/workerd.ts
@@ -49,6 +49,14 @@ export interface ServiceDesignator {
 	props?: { json: string };
 }
 
+export type Worker_DockerConfiguration = {
+	socketPath: string;
+};
+
+export type Worker_ContainerEngine = {
+	localDocker: Worker_DockerConfiguration;
+};
+
 export type Worker = (
 	| { modules?: Worker_Module[] }
 	| { serviceWorkerScript?: string }
@@ -64,6 +72,7 @@ export type Worker = (
 	durableObjectStorage?: Worker_DurableObjectStorage;
 	moduleFallback?: string;
 	tails?: ServiceDesignator[];
+	containerEngine?: Worker_ContainerEngine;
 };
 
 export type Worker_DurableObjectStorage =
diff --git a/packages/wrangler/src/__tests__/config-validation-pages.test.ts b/packages/wrangler/src/__tests__/config-validation-pages.test.ts
@@ -181,6 +181,7 @@ describe("validatePagesConfig()", () => {
 						upstream_protocol: "https",
 						host: "test-host",
 						enable_containers: false,
+						container_engine: undefined,
 					},
 				},
 			};
diff --git a/packages/wrangler/src/api/dev.ts b/packages/wrangler/src/api/dev.ts
@@ -1,7 +1,10 @@
 import events from "node:events";
 import { fetch, Request } from "undici";
 import { startDev } from "../dev";
-import { getDockerPath } from "../environment-variables/misc-variables";
+import {
+	getDockerHost,
+	getDockerPath,
+} from "../environment-variables/misc-variables";
 import { run } from "../experimental-flags";
 import { logger } from "../logger";
 import type { Environment } from "../config";
@@ -88,6 +91,7 @@ export interface Unstable_DevOptions {
 		enableIpc?: boolean;
 		enableContainers?: boolean; // Whether to build and connect to containers in dev mode. Defaults to true.
 		dockerPath?: string; // Path to the docker binary, if not on $PATH
+		containerEngine?: string; // Docker socket
 	};
 }
 
@@ -224,6 +228,7 @@ export async function unstable_dev(
 		nodeCompat: undefined,
 		enableContainers: options?.experimental?.enableContainers ?? false,
 		dockerPath: options?.experimental?.dockerPath ?? getDockerPath(),
+		containerEngine: options?.experimental?.containerEngine ?? getDockerHost(),
 	};
 
 	//outside of test mode, rebuilds work fine, but only one instance of wrangler will work at a time
diff --git a/packages/wrangler/src/api/startDevWorker/ConfigController.ts b/packages/wrangler/src/api/startDevWorker/ConfigController.ts
@@ -12,7 +12,10 @@ import {
 } from "../../dev";
 import { getClassNamesWhichUseSQLite } from "../../dev/class-names-sqlite";
 import { getLocalPersistencePath } from "../../dev/get-local-persistence-path";
-import { getDockerPath } from "../../environment-variables/misc-variables";
+import {
+	getDockerHost,
+	getDockerPath,
+} from "../../environment-variables/misc-variables";
 import { UserError } from "../../errors";
 import { getFlag } from "../../experimental-flags";
 import { logger, runWithLogLevel } from "../../logger";
@@ -155,6 +158,7 @@ async function resolveDevConfig(
 		enableContainers:
 			input.dev?.enableContainers ?? config.dev.enable_containers,
 		dockerPath: input.dev?.dockerPath ?? getDockerPath(),
+		containerEngine: input.dev?.containerEngine ?? getDockerHost(),
 	} satisfies StartDevWorkerOptions["dev"];
 }
 
@@ -433,6 +437,9 @@ function resolveContainerConfig(
 	config: Config
 ): StartDevWorkerOptions["containers"] {
 	const containers: WorkerOptions["containers"] = {};
+	if (!config.dev.enable_containers) {
+		return containers;
+	}
 	for (const container of config.containers ?? []) {
 		containers[container.class_name] = {
 			image: container.image ?? container.configuration.image,
diff --git a/packages/wrangler/src/api/startDevWorker/LocalRuntimeController.ts b/packages/wrangler/src/api/startDevWorker/LocalRuntimeController.ts
@@ -136,6 +136,7 @@ export async function convertToConfigBundle(
 		containers: event.config.containers ?? {},
 		enableContainers: event.config.dev.enableContainers ?? true,
 		dockerPath: event.config.dev.dockerPath ?? "docker",
+		containerEngine: event.config.dev.containerEngine,
 	};
 }
 
diff --git a/packages/wrangler/src/api/startDevWorker/types.ts b/packages/wrangler/src/api/startDevWorker/types.ts
@@ -1,6 +1,7 @@
 import type { AssetsOptions } from "../../assets";
 import type { Config } from "../../config";
 import type {
+	ContainerEngine,
 	CustomDomainRoute,
 	DurableObjectMigration,
 	Rule,
@@ -190,6 +191,9 @@ export interface StartDevWorkerInput {
 
 		/** Path to the docker executable. Defaults to 'docker' */
 		dockerPath?: string;
+
+		/** Options for the container engine */
+		containerEngine?: ContainerEngine;
 	};
 	legacy?: {
 		site?: Hook<Config["site"], [Config]>;
diff --git a/packages/wrangler/src/config/config.ts b/packages/wrangler/src/config/config.ts
@@ -1,4 +1,8 @@
-import type { Environment, RawEnvironment } from "./environment";
+import type {
+	ContainerEngine,
+	Environment,
+	RawEnvironment,
+} from "./environment";
 import type { CamelCaseKey } from "yargs";
 
 /**
@@ -238,6 +242,12 @@ export interface DevConfig {
 	 * @default true
 	 */
 	enable_containers: boolean;
+
+	/**
+	 * Either the Docker unix socket i.e. `unix:/var/run/docker.sock` or a full configuration.
+	 * Note that windows is only supported via WSL at the moment
+	 */
+	container_engine: ContainerEngine | undefined;
 }
 
 export type RawDevConfig = Partial<DevConfig>;
@@ -287,6 +297,7 @@ export const defaultWranglerConfig: Config = {
 		host: undefined,
 		// Note this one is also workers only
 		enable_containers: true,
+		container_engine: undefined,
 	},
 
 	/** INHERITABLE ENVIRONMENT FIELDS **/
diff --git a/packages/wrangler/src/config/environment.ts b/packages/wrangler/src/config/environment.ts
@@ -541,6 +541,9 @@ export interface EnvironmentNonInheritable {
 	/**
 	 * Container related configuration
 	 *
+	 * NOTE: This field is not automatically inherited from the top level environment,
+	 * and so must be specified in every named environment.
+	 *
 	 * @default []
 	 * @nonInheritable
 	 */
@@ -1094,3 +1097,14 @@ export interface Observability {
 		invocation_logs?: boolean;
 	};
 }
+
+export type DockerConfiguration = {
+	/** Socket used by miniflare to communicate with Docker */
+	socketPath: string;
+};
+
+export type ContainerEngine =
+	| {
+			localDocker: DockerConfiguration;
+	  }
+	| string;
diff --git a/packages/wrangler/src/config/validation.ts b/packages/wrangler/src/config/validation.ts
diff --git a/packages/wrangler/src/dev.ts b/packages/wrangler/src/dev.ts
diff --git a/packages/wrangler/src/dev/miniflare.ts b/packages/wrangler/src/dev/miniflare.ts
diff --git a/packages/wrangler/src/environment-variables/factory.ts b/packages/wrangler/src/environment-variables/factory.ts
diff --git a/packages/wrangler/src/environment-variables/misc-variables.ts b/packages/wrangler/src/environment-variables/misc-variables.ts
diff --git a/packages/wrangler/turbo.json b/packages/wrangler/turbo.json

Original file line number	Diff line number	Diff line change
`@@ -23,6 +23,7 @@ import {`
`23`	`23`	`sanitisePath,`
`24`	`24`	`} from "../../workers";`
`25`	`25`	`import { UnsafeUniqueKey } from "./constants";`
	`26`	`+import type { DOContainerOptions } from "../do";`
`26`	`27`
`27`	`28`	`export const DEFAULT_PERSIST_ROOT = ".mf";`
`28`	`29`
`@@ -47,6 +48,7 @@ export type DurableObjectClassNames = Map<`
`47`	`48`	`enableSql?: boolean;`
`48`	`49`	`unsafeUniqueKey?: UnsafeUniqueKey;`
`49`	`50`	`unsafePreventEviction?: boolean;`
	`51`	`+ container?: DOContainerOptions;`
`50`	`52`	`}`
`51`	`53`	`>`
`52`	`54`	`>;`