@alchemy.run/docker 0.0.0 → 2.0.0-beta.85

package/src/Container.ts

@@ -0,0 +1,1118 @@
+import { Unowned } from "alchemy/AdoptPolicy";
+import { isResolved } from "alchemy/Diff";
+import * as Provider from "alchemy/Provider";
+import { Resource } from "alchemy/Resource";
+import { createInternalTags, hasAlchemyTags } from "alchemy/Tags";
+import { toSeconds } from "alchemy/Util/Duration";
+import { sha256, sha256Object } from "alchemy/Util/sha256";
+import * as Data from "effect/Data";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Equal from "effect/Equal";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import type { PlatformError } from "effect/PlatformError";
+import * as Redacted from "effect/Redacted";
+import { Docker, dockerContextName, dockerPhysicalName } from "./Docker.ts";
+import { healthcheckCommand, isHealthcheckDisabled } from "./HealthcheckCommand.ts";
+import type { Providers } from "./Providers.ts";
+
+const CREATE_CONFIG_HASH_LABEL = "alchemy::container-config";
+
+export interface ContainerProps {
+  /** Image reference or Docker image resource. */
+  image: Container.Image;
+  /** Docker context name or context resource. */
+  context?: Docker.ContextRef;
+  /**
+   * Container name.
+   *
+   * @default Generated from stack, stage, logical id, and instance id.
+   */
+  name?: string;
+  /** Command to run in the container. */
+  command?: string[];
+  /** Container environment variables. Use Redacted for secrets. */
+  environment?: Record<string, string | Redacted.Redacted<string>>;
+  /**
+   * Paths to Docker env files, forwarded in the declared order as repeated
+   * `--env-file` options. Explicit `environment` values are forwarded after
+   * these files and take precedence in Docker. Editing a file's contents
+   * replaces the container on the next deploy. Only a digest of the contents
+   * is kept, on the container's own label; neither contents nor digest are
+   * written to Alchemy state. Docker itself exposes the resolved values
+   * through `docker inspect`, so treat env files as secrets.
+   */
+  envFiles?: string[];
+  /** Host/container port mappings. */
+  ports?: Container.PortMapping[];
+  /** Volume or bind mounts. */
+  volumes?: Container.VolumeMapping[];
+  /** Restart policy. */
+  restart?: "no" | "always" | "on-failure" | "unless-stopped";
+  /**
+   * Container labels. Alchemy's internal ownership labels are added
+   * automatically.
+   */
+  labels?: Record<string, string>;
+  /**
+   * Grace period before Docker forcefully kills the container after stopping
+   * it.
+   */
+  stopTimeout?: Duration.Input;
+  /** Networks to connect after create. */
+  networks?: Container.NetworkMapping[];
+  /** Network namespace. Use `{ container: id }` to share another container's namespace. */
+  networkMode?: Container.NetworkMode;
+  /** Linux capabilities to add, for example `SYS_ADMIN`. */
+  capAdd?: string[];
+  /** Linux capabilities to drop, for example `["ALL"]`. */
+  capDrop?: string[];
+  /** Hard memory limit in Docker's byte-suffix format, e.g. `"512m"`. */
+  memory?: string;
+  /**
+   * Combined memory-plus-swap limit in Docker's byte-suffix format.
+   * Requires `memory`. Set to the same value to disable swap, or `"-1"`
+   * to allow unlimited swap (subject to the host).
+   */
+  memorySwap?: string;
+  /** Soft memory limit under contention, e.g. `"256m"`. */
+  memoryReservation?: string;
+  /** CPU quota, in cores (e.g. `0.5` limits to half a CPU). */
+  cpus?: number;
+  /** Maximum number of processes and threads in the container. */
+  pidsLimit?: number;
+  /** Mount the container's root filesystem read-only. Writable paths need a volume or tmpfs. */
+  readOnlyRootFilesystem?: boolean;
+  /** Prevent processes from gaining additional privileges through exec. */
+  noNewPrivileges?: boolean;
+  /** Run Docker's init process to forward signals and reap child processes. */
+  init?: boolean;
+  /** Runtime user, e.g. `"1000:1000"` or `"app"`. Omit to keep the image's user. */
+  user?: string;
+  /**
+   * Seccomp JSON profile path on the Docker CLI host, or `"builtin"` to
+   * select Docker's default policy. `"unconfined"` explicitly disables it.
+   * Changes to a profile file's contents recreate the container.
+   */
+  seccompProfile?: string;
+  /**
+   * Name of a preloaded AppArmor profile, e.g. `"docker-default"`.
+   * Requires AppArmor support on the target host. `"unconfined"` disables it.
+   */
+  appArmorProfile?: string;
+  /** Docker user-namespace mode. `"host"` opts out of daemon user remapping. */
+  userNamespace?: string;
+  /** Supplementary Linux group names or numeric GIDs. */
+  groupAdd?: string[];
+  /** Per-process resource limits. `-1` represents unlimited. */
+  ulimits?: Record<string, Container.Ulimit>;
+  /** Docker log driver, e.g. `"local"`, `"json-file"`, or `"none"`. */
+  logDriver?: string;
+  /** Driver-specific settings, such as `{ "max-size": "10m", "max-file": "3" }`. */
+  logOptions?: Record<string, string>;
+  /** Relative OOM score adjustment on Linux, from -1000 to 1000. */
+  oomScoreAdjustment?: number;
+  /** Stop signal, e.g. `"SIGTERM"` or `"SIGINT"`. */
+  stopSignal?: string;
+  /** Writable in-memory mounts, including size and POSIX mode controls. */
+  tmpfs?: Container.TmpfsMount[];
+  /** Host devices to expose to the container. */
+  devices?: Container.DeviceMapping[];
+  /**
+   * Extra `/etc/hosts` entries, each `hostname:address`. Docker's
+   * `host-gateway` alias resolves to the host machine, so
+   * `"host.docker.internal:host-gateway"` reaches services listening on the
+   * developer's machine from inside the container.
+   *
+   * On Linux `host-gateway` is the bridge gateway address, so those packets
+   * traverse the host's `INPUT` chain — under a default-deny firewall the
+   * name resolves and the connection then times out. See the Host Access
+   * examples.
+   */
+  extraHosts?: string[];
+  /** Remove the container when it exits. @default false */
+  removeOnExit?: boolean;
+  /** Start the container after creation/reconciliation. @default false */
+  start?: boolean;
+  /** Docker healthcheck configuration. */
+  healthcheck?: Container.Healthcheck;
+}
+
+export declare namespace Container {
+  type Status = "created" | "running" | "paused" | "restarting" | "removing" | "exited" | "dead";
+  type Image = string | { imageRef: string; imageId?: string };
+  interface PortMapping {
+    /** External port on the host. */
+    external: number | string;
+    /** Internal port inside the container. */
+    internal: number | string;
+    /** Protocol used for the mapping. @default "tcp" */
+    protocol?: "tcp" | "udp";
+  }
+  interface VolumeMapping {
+    /** Host path or named volume source. */
+    hostPath: string;
+    /** Container path. */
+    containerPath: string;
+    /** Mount read-only. @default false */
+    readOnly?: boolean;
+  }
+  interface TmpfsMount {
+    /** Absolute mount target in the container, e.g. `"/tmp"`. */
+    path: string;
+    /** Docker byte-suffix size, e.g. `"32m"`. Omit for the engine default. */
+    size?: string;
+    /** POSIX mode as a number, e.g. `0o1777` for a sticky world-writable directory. */
+    mode?: number;
+  }
+  interface Ulimit {
+    /** Process soft limit. `-1` means unlimited. */
+    soft: number;
+    /** Process hard limit. `-1` means unlimited. */
+    hard: number;
+  }
+  interface NetworkMapping {
+    /** Network name or ID. */
+    name: string;
+    /** Network aliases for the container. */
+    aliases?: string[];
+  }
+  type NetworkMode = string | { container: string };
+  interface DeviceMapping {
+    /** Host device path. */
+    hostPath: string;
+    /** Container device path. */
+    containerPath: string;
+    /** Cgroup permissions. @default "rwm" */
+    permissions?: string;
+  }
+  interface Healthcheck {
+    /**
+     * Command to run for health checks. A string runs in the container's
+     * shell. An array follows Docker's healthcheck `Test` form:
+     * `["CMD-SHELL", "pg_isready -U app"]`, `["CMD", "pg_isready", "-U", "app"]`,
+     * or `["NONE"]` to disable the image's healthcheck.
+     */
+    cmd: string[] | string;
+    /** Time between checks. */
+    interval?: Duration.Input;
+    /** Maximum time a check may run. */
+    timeout?: Duration.Input;
+    /** Consecutive failures before unhealthy. */
+    retries?: number;
+    /** Startup grace period. */
+    startPeriod?: Duration.Input;
+    /** Check interval during startup. Requires Docker API 1.44+. */
+    startInterval?: Duration.Input;
+  }
+}
+
+export interface Container extends Resource<
+  "Docker.Container",
+  ContainerProps,
+  {
+    /** Docker container id. */
+    id: string;
+    /** Docker container name. */
+    name: string;
+    /** Docker container state. */
+    status: Container.Status;
+    /** Creation timestamp in milliseconds since epoch. */
+    createdAt: number;
+    /** Image reference used to create the container. */
+    imageRef: string;
+    /**
+     * Map of internal container ports to their bound host ports.
+     * Format: `"80/tcp" -> 8080`.
+     */
+    ports: Record<string, number>;
+    /** Configured network namespace, when reported by Docker. */
+    networkMode?: string;
+    /** Added Linux capabilities, when reported by Docker. */
+    capAdd?: string[];
+    /** Configured host devices, when reported by Docker. */
+    devices?: Container.DeviceMapping[];
+  },
+  never,
+  Providers
+> {}
+
+/**
+ * A Docker container managed through the active Docker context.
+ *
+ * This resource creates, starts, stops, inspects, and removes containers through
+ * the Docker CLI. It is not interchangeable with `Cloudflare.Container`, which
+ * manages Cloudflare's container platform; use pushed image references to bridge
+ * Docker-built images into cloud container runtimes.
+ *
+ *
+ * ### Running Containers
+ * **Example:** Nginx with a published port
+ * ```typescript
+ * const nginx = yield* Docker.Container("nginx", {
+ *   image: "nginx:alpine",
+ *   ports: [{ external: 8080, internal: 80 }],
+ *   start: true,
+ * });
+ * ```
+ *
+ * ### Secret Environment
+ * **Example:** Redacted env var
+ * ```typescript
+ * const password = yield* Config.Redacted("POSTGRES_PASSWORD");
+ * const db = yield* Docker.Container("postgres", {
+ *   image: "postgres:18-alpine",
+ *   environment: {
+ *     POSTGRES_PASSWORD: password,
+ *   },
+ *   start: true,
+ * });
+ * ```
+ *
+ * ### Environment Files
+ * **Example:** Layered Docker env files
+ * ```typescript
+ * const app = yield* Docker.Container("app", {
+ *   image: "ghcr.io/acme/app:latest",
+ *   envFiles: ["./config/base.env", "./config/production.env"],
+ *   // Explicit values are passed after env files and take precedence.
+ *   environment: { LOG_LEVEL: "info" },
+ * });
+ * ```
+ *
+ * Editing an env file replaces the container on the next deploy, as does
+ * adopting a container that uses env files (once, so later edits are tracked).
+ * Alchemy reads
+ * the files at plan time but keeps only a digest of their contents, on the
+ * container's own label; neither the values nor the digest are written to
+ * Alchemy state. Docker exposes the resolved values through `docker inspect`,
+ * so treat env files as secrets.
+ *
+ * ### Networks and Volumes
+ * **Example:** PostgreSQL with persistent storage
+ * ```typescript
+ * const network = yield* Docker.Network("app-network");
+ * const data = yield* Docker.Volume("postgres-data");
+ * const postgresName = "app-postgres";
+ * yield* Docker.Container("postgres", {
+ *   name: postgresName,
+ *   image: "postgres:18-alpine",
+ *   ports: [{ external: 15432, internal: 5432 }],
+ *   volumes: [{ hostPath: data.name, containerPath: "/var/lib/postgresql/data" }],
+ *   networks: [{ name: network.name, aliases: ["postgres"] }],
+ *   start: true,
+ * });
+ * const runtime = yield* Docker.inspectContainer(postgresName);
+ * ```
+ *
+ * ### Host Access
+ * `extraHosts` writes lines into the container's `/etc/hosts`; it changes name
+ * resolution and nothing else. Docker's `host-gateway` alias resolves to the
+ * host machine, which is how a container reaches a service on the developer's
+ * loopback.
+ *
+ * On Linux `host-gateway` is the Docker bridge gateway (typically
+ * `172.17.0.1`), so a container's packets to it arrive on the host's `INPUT`
+ * chain. Under a default-deny firewall — ufw ships
+ * `DEFAULT_INPUT_POLICY="DROP"` — the hostname resolves correctly and the
+ * connection then times out, which reads like an application bug rather than a
+ * firewall one. Allow the bridge subnet to fix it:
+ * `sudo ufw allow from 172.16.0.0/12`.
+ *
+ * **Example:** Reach a service on the developer's machine
+ * ```typescript
+ * const api = yield* Docker.Container("api", {
+ *   image: "ghcr.io/acme/api:latest",
+ *   // `host-gateway` resolves to the host machine, so a database listening
+ *   // on the developer's loopback is reachable from inside the container.
+ *   extraHosts: ["host.docker.internal:host-gateway"],
+ *   environment: {
+ *     DATABASE_URL: "postgres://postgres@host.docker.internal:5432/app",
+ *   },
+ *   start: true,
+ * });
+ * ```
+ *
+ * **Example:** Pin a hostname to a fixed address
+ * ```typescript
+ * const api = yield* Docker.Container("api", {
+ *   image: "ghcr.io/acme/api:latest",
+ *   // Any `hostname:address` pair — host access is just the common case.
+ *   extraHosts: ["service.example:192.0.2.10"],
+ *   start: true,
+ * });
+ * ```
+ *
+ * ### Runtime Options
+ * **Example:** Contain a background worker
+ * ```typescript
+ * const worker = yield* Docker.Container("worker", {
+ *   image: "oven/bun:1",
+ *   memory: "512m",
+ *   memorySwap: "512m",
+ *   memoryReservation: "256m",
+ *   cpus: 0.5,
+ *   pidsLimit: 128,
+ *   readOnlyRootFilesystem: true,
+ *   capDrop: ["ALL"],
+ *   noNewPrivileges: true,
+ *   init: true,
+ *   user: "1000:1000",
+ *   tmpfs: [{ path: "/tmp", size: "32m", mode: 0o1777 }],
+ * });
+ * ```
+ *
+ * **Example:** Customize confinement, process limits, and log rotation
+ * ```typescript
+ * const api = yield* Docker.Container("api", {
+ *   image: "ghcr.io/acme/api:latest",
+ *   seccompProfile: "./security/api-seccomp.json", // client-side JSON; edits roll the container
+ *   appArmorProfile: "my-loaded-profile",          // must already be loaded on the host
+ *   groupAdd: ["1000"],
+ *   ulimits: { nofile: { soft: 1024, hard: 4096 } },
+ *   logDriver: "local",
+ *   logOptions: { "max-size": "10m", "max-file": "3" },
+ *   oomScoreAdjustment: 200,
+ *   stopSignal: "SIGTERM",
+ * });
+ * ```
+ *
+ * **Example:** Share a donor container's network namespace
+ * ```typescript
+ * const donor = yield* Docker.Container("donor", { image: "redis:alpine" });
+ * const sidecar = yield* Docker.Container("sidecar", {
+ *   image: "busybox:latest",
+ *   networkMode: { container: donor.id },
+ * });
+ * ```
+ *
+ * **Example:** Add capabilities and devices
+ * ```typescript
+ * const worker = yield* Docker.Container("worker", {
+ *   image: "ubuntu:latest",
+ *   capAdd: ["SYS_ADMIN"],
+ *   devices: [{ hostPath: "/dev/fuse", containerPath: "/dev/fuse" }],
+ * });
+ * ```
+ *
+ * **Example:** Publish on any free host port
+ * ```typescript
+ * const api = yield* Docker.Container("api", {
+ *   image: "ghcr.io/acme/api:latest",
+ *   // `external: 0` lets Docker choose; the assigned port is reported back.
+ *   ports: [{ external: 0, internal: 3000 }],
+ *   start: true,
+ * });
+ * const hostPort = api.ports["3000/tcp"];
+ * ```
+ *
+ * ### Traefik
+ * **Example:** Route a container through Traefik
+ * ```typescript
+ * const api = yield* Docker.Container("api", {
+ *   image: "ghcr.io/acme/api:latest",
+ *   networks: [{ name: "traefik" }],
+ *   labels: {
+ *     "traefik.enable": "true",
+ *     "traefik.http.routers.api.rule": "Host(`api.example.com`)",
+ *     "traefik.http.services.api.loadbalancer.server.port": "3000",
+ *   },
+ *   stopTimeout: "30 seconds",
+ *   start: true,
+ * });
+ * ```
+ *
+ * **Example:** Use a Docker.Context resource
+ * ```typescript
+ * const remote = yield* Docker.Context("remote", {
+ *   name: "remote-build",
+ *   docker: "host=ssh://docker@example.com",
+ * });
+ *
+ * const api = yield* Docker.Container("api", {
+ *   image: "nginx:alpine",
+ *   context: remote,
+ * });
+ * ```
+ *
+ * @resource
+ * @product Container
+ */
+export const Container = Resource<Container>("Docker.Container");
+
+/**
+ * Inspect a Docker container by name and return normalized runtime details.
+ *
+ * This is a small public wrapper around Docker's raw inspect output. It returns
+ * the stable data Alchemy callers typically need, including bound host ports.
+ */
+export const inspectContainer = (
+  name: string,
+  context?: Docker.ContextRef,
+): Effect.Effect<Container["Attributes"], PlatformError, Docker> =>
+  Docker.pipe(
+    Effect.flatMap((docker) => docker.container.inspect(name, dockerContextName(context))),
+    Effect.map((container) => toContainerAttributes(container, container.Config.Image)),
+  );
+
+export const ContainerProvider = () =>
+  Provider.effect(
+    Container,
+    Effect.gen(function* () {
+      const docker = yield* Docker;
+      const fs = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+
+      // Env files are read so editing one rolls the container, but only a
+      // digest of their bytes enters the config hash, which lives solely in
+      // the container's own label (where `docker inspect` already exposes
+      // the resolved values). Neither contents nor digest reach alchemy state.
+      const envFilesDigest = Effect.fn(function* (envFiles: ReadonlyArray<string> | undefined) {
+        if (!envFiles?.length) return undefined;
+        const digests = yield* Effect.forEach(envFiles, (file) =>
+          fs.readFile(path.resolve(file)).pipe(
+            Effect.flatMap(sha256),
+            Effect.map((digest) => `${file}\0${digest}`),
+          ),
+        );
+        return yield* sha256(digests.join("\n"));
+      });
+
+      // Docker CLI loads seccomp profiles from client-side files at create
+      // time. Hash the contents as well as the path so policy edits are never
+      // silently ignored on subsequent deploys.
+      const seccompProfileDigest = Effect.fn(function* (profile: string | undefined) {
+        if (!isCustomSeccompProfile(profile)) return undefined;
+        return yield* fs.readFile(path.resolve(profile)).pipe(Effect.flatMap(sha256));
+      });
+
+      // Without env files the hash input is unchanged from before they were
+      // supported, so existing containers keep their label and are not rolled.
+      const desiredConfigHash = Effect.fn(function* (
+        args: Parameters<Docker["Service"]["container"]["create"]>[0],
+        news: ContainerProps,
+      ) {
+        const envFiles = yield* envFilesDigest(news.envFiles);
+        const seccompProfile = yield* seccompProfileDigest(news.seccompProfile);
+        return yield* sha256Object({
+          ...args,
+          imageId: normalizeImageId(news.image),
+          ...(envFiles === undefined ? {} : { envFiles }),
+          ...(seccompProfile === undefined ? {} : { seccompProfile }),
+        });
+      });
+
+      const reconcileNetworks = Effect.fn(function* (
+        live: Docker.Container,
+        news: ContainerProps,
+        olds: ContainerProps | undefined,
+      ) {
+        const context = dockerContextName(news.context);
+        const connect = new Map<string, Container.NetworkMapping>();
+        const disconnect = new Set<string>();
+        for (const network of news.networks ?? []) {
+          const entry = live.NetworkSettings.Networks?.[network.name];
+          if (!entry) {
+            connect.set(network.name, network);
+          } else if (!Equal.equals(entry.Aliases ?? [], network.aliases ?? [])) {
+            connect.set(network.name, network);
+            disconnect.add(network.name);
+          }
+        }
+        // Only networks alchemy itself attached are alchemy's to detach, and
+        // `olds.networks` is the sole record of which those are — the live
+        // container cannot say who connected a network. Sweeping every live
+        // network instead tore off the default `bridge` and anything a user,
+        // compose file, or another tool had attached out of band (#1386).
+        const desired = new Set((news.networks ?? []).map((n) => n.name));
+        for (const network of olds?.networks ?? []) {
+          if (!desired.has(network.name) && live.NetworkSettings.Networks?.[network.name]) {
+            disconnect.add(network.name);
+          }
+        }
+        yield* Effect.forEach(
+          disconnect,
+          (network) => docker.network.disconnect({ network, container: live.Id, context }),
+          { concurrency: "unbounded" },
+        );
+        yield* Effect.forEach(
+          connect.values(),
+          (network) =>
+            docker.network.connect({
+              network: network.name,
+              container: live.Id,
+              alias: network.aliases,
+              context,
+            }),
+          { concurrency: "unbounded" },
+        );
+      });
+
+      const inspect = (name: string, context?: string) =>
+        docker.container
+          .inspect(name, context)
+          .pipe(Effect.catchReason("PlatformError", "NotFound", () => Effect.undefined));
+
+      const remove = (name: string, context?: string) =>
+        docker.container.stop(name, context).pipe(
+          Effect.andThen(docker.container.remove(name, true, context)),
+          Effect.catchReason("PlatformError", "NotFound", () => Effect.void),
+        );
+
+      return Container.Provider.of({
+        list: () => Effect.succeed([]),
+        read: Effect.fn(function* ({ id, instanceId, olds, output }) {
+          const context = dockerContextName(olds.context);
+          const name = yield* dockerPhysicalName(id, olds, instanceId);
+          const info = yield* inspect(name, context);
+          if (!info) return undefined;
+          // `olds.image` may be `undefined` when a `creating` row was
+          // persisted before upstream Outputs resolved — fall back to the
+          // live container's actual image.
+          const attrs = toContainerAttributes(
+            info,
+            olds.image !== undefined ? normalizeImageRef(olds.image) : info.Config.Image,
+          );
+          if (output) return attrs;
+          // Without prior state, only adopt a container that carries our
+          // branding; anything else is foreign and gated behind `--adopt`.
+          const owned = yield* hasAlchemyTags(id, info.Config.Labels ?? undefined);
+          return owned ? attrs : Unowned(attrs);
+        }),
+        diff: Effect.fn(function* ({ id, instanceId, news, olds }) {
+          if (!isResolved(news)) return undefined;
+          // An Output-valued `image` doesn't survive a `creating`-state
+          // round-trip (it deserializes as `undefined`) — without comparable
+          // prior create args, let the engine apply its default update logic.
+          if (olds.image === undefined) return undefined;
+          if (dockerContextName(olds.context) !== dockerContextName(news.context)) {
+            return { action: "replace" as const, deleteFirst: true };
+          }
+          const oldArgs = yield* makeCreateArgs(id, olds, instanceId);
+          const newArgs = yield* makeCreateArgs(id, news, instanceId);
+          if (!Equal.equals(oldArgs, newArgs)) {
+            return { action: "replace" as const, deleteFirst: true };
+          }
+          if (
+            !Equal.equals(olds.networks ?? [], news.networks ?? []) ||
+            (olds.start ?? false) !== (news.start ?? false)
+          ) {
+            return { action: "update" as const };
+          }
+          // File-backed inputs can change without changing their paths.
+          // Compare their digests against the live config hash.
+          if (news.envFiles?.length || isCustomSeccompProfile(news.seccompProfile)) {
+            const live = yield* inspect(newArgs.name, dockerContextName(news.context));
+            const applied = live?.Config.Labels?.[CREATE_CONFIG_HASH_LABEL];
+            if (applied !== undefined && applied !== (yield* desiredConfigHash(newArgs, news))) {
+              return { action: "update" as const };
+            }
+          }
+        }),
+        reconcile: Effect.fn(function* ({ id, instanceId, news, olds, output }) {
+          const context = dockerContextName(news.context);
+          const args = yield* makeCreateArgs(id, news, instanceId);
+          const configHash = yield* desiredConfigHash(args, news);
+          // Adoption has output but no olds. In that case the observed
+          // container already lives in the desired context.
+          const oldContext = olds ? dockerContextName(olds.context) : context;
+          const desiredLive = yield* inspect(args.name, context);
+          const previous =
+            output && (output.name !== args.name || oldContext !== context)
+              ? yield* inspect(output.name, oldContext)
+              : undefined;
+          if (previous) {
+            yield* remove(previous.Id, oldContext);
+          }
+          const live = desiredLive?.Id === previous?.Id ? undefined : desiredLive;
+
+          const oldArgs =
+            live?.Config.Labels?.[CREATE_CONFIG_HASH_LABEL] === undefined && olds !== undefined
+              ? yield* makeCreateArgs(
+                  id,
+                  {
+                    ...olds,
+                    image: olds.image ?? output?.imageRef ?? news.image,
+                  },
+                  instanceId,
+                )
+              : undefined;
+          const recreate =
+            live !== undefined &&
+            (live.Config.Labels?.[CREATE_CONFIG_HASH_LABEL] === undefined
+              ? (oldArgs !== undefined && !Equal.equals(oldArgs, args)) ||
+                normalizeImageId(olds?.image) !== normalizeImageId(news.image) ||
+                !matchesLegacyConfig(live, args, news.image) ||
+                // Env file contents can't be compared without a label (e.g. an
+                // adopted container); recreate once so later edits are tracked.
+                (news.envFiles?.length ?? 0) > 0 ||
+                isCustomSeccompProfile(news.seccompProfile) ||
+                // A legacy/adopted container has no stamped config hash.
+                // Do not retain it without proof that the requested security
+                // restrictions were applied.
+                hasHardeningOptions(news)
+              : live.Config.Labels[CREATE_CONFIG_HASH_LABEL] !== configHash);
+          if (recreate) {
+            yield* remove(live.Id, context);
+          }
+
+          const current = recreate ? undefined : live;
+          if (!current) {
+            const internalTags = yield* createInternalTags(id);
+            const { stdout: containerId } = yield* docker.container.create({
+              ...args,
+              context,
+              label: {
+                ...args.label,
+                ...internalTags,
+                [CREATE_CONFIG_HASH_LABEL]: configHash,
+              },
+            });
+            yield* Effect.forEach(
+              news.networks ?? [],
+              (network) =>
+                docker.network.connect({
+                  network: network.name,
+                  container: containerId,
+                  alias: network.aliases,
+                  context,
+                }),
+              { concurrency: "unbounded" },
+            );
+            if (news.start) {
+              yield* docker.container.start(containerId, context);
+            }
+            const info = yield* docker.container.inspect(containerId, context);
+            return toContainerAttributes(info, args.image);
+          }
+
+          yield* reconcileNetworks(current, news, olds);
+          if (news.start && current.State.Status !== "running") {
+            yield* docker.container.start(current.Id, context);
+          } else if (!news.start && current.State.Status === "running") {
+            yield* docker.container.stop(current.Id, context);
+          }
+          return yield* docker.container
+            .inspect(current.Id, context)
+            .pipe(Effect.map((info) => toContainerAttributes(info, args.image)));
+        }),
+        delete: Effect.fn(({ olds, output }) =>
+          remove(output.name, dockerContextName(olds.context)),
+        ),
+      });
+    }),
+  );
+
+const normalizeImageRef = (image: Container.Image): string =>
+  typeof image === "string" ? image : image.imageRef;
+
+const normalizeImageId = (image: Container.Image | undefined) =>
+  typeof image === "string" ? undefined : image?.imageId;
+
+type CreateArgs = Parameters<Docker["Service"]["container"]["create"]>[0];
+
+// Containers created before config hashes were introduced are compared using
+// the fields Docker reports without image-default normalization. A subsequent
+// create stamps the complete resolved configuration hash.
+const matchesLegacyConfig = (live: Docker.Container, desired: CreateArgs, image: Container.Image) =>
+  (normalizeImageId(image)
+    ? live.Image === normalizeImageId(image)
+    : live.Config.Image === desired.image) &&
+  (desired.command === undefined || Equal.equals(live.Config.Cmd, desired.command)) &&
+  Object.entries(desired.env ?? {}).every(([key, value]) =>
+    live.Config.Env?.includes(`${key}=${value}`),
+  );
+
+const makeCreateArgs = (id: string, news: ContainerProps, instanceId: string) =>
+  dockerPhysicalName(id, news, instanceId).pipe(
+    Effect.tap(() => validateContainerOptions(news)),
+    Effect.map((name): Parameters<Docker["Service"]["container"]["create"]>[0] => ({
+      name,
+      image: normalizeImageRef(news.image),
+      command: news.command,
+      env: normalizeEnvironment(news.environment),
+      "env-file": news.envFiles?.length ? news.envFiles : undefined,
+      volume: news.volumes?.map(
+        (v) => `${v.hostPath}:${v.containerPath}${v.readOnly ? ":ro" : ""}`,
+      ),
+      p: news.ports?.map((port) => {
+        const target = `${port.internal}/${port.protocol ?? "tcp"}`;
+        // `external: 0` means "any free host port". Docker spells that as a
+        // bare container port (`-p 80/tcp`); `-p 0:80/tcp` instead asks for
+        // host port 0 literally, which the daemon accepts and then reports
+        // back as 0.
+        return isRandomHostPort(port.external) ? target : `${port.external}:${target}`;
+      }),
+      "add-host": news.extraHosts,
+      network: normalizeNetworkMode(news.networkMode),
+      "cap-add": normalizeCapabilities(news.capAdd),
+      ...(news.capDrop?.length ? { "cap-drop": normalizeCapabilities(news.capDrop) } : {}),
+      ...(news.memory !== undefined ? { memory: news.memory } : {}),
+      ...(news.memorySwap !== undefined ? { "memory-swap": news.memorySwap } : {}),
+      ...(news.memoryReservation !== undefined
+        ? { "memory-reservation": news.memoryReservation }
+        : {}),
+      ...(news.cpus !== undefined ? { cpus: news.cpus } : {}),
+      ...(news.pidsLimit !== undefined ? { "pids-limit": news.pidsLimit } : {}),
+      ...(news.readOnlyRootFilesystem ? { "read-only": true } : {}),
+      ...(normalizeSecurityOptions(news) ? { "security-opt": normalizeSecurityOptions(news) } : {}),
+      ...(news.userNamespace !== undefined ? { userns: news.userNamespace } : {}),
+      ...(news.groupAdd?.length ? { "group-add": normalizeGroups(news.groupAdd) } : {}),
+      ...(Object.keys(news.ulimits ?? {}).length ? { ulimit: normalizeUlimits(news.ulimits) } : {}),
+      ...(news.logDriver !== undefined ? { "log-driver": news.logDriver } : {}),
+      ...(Object.keys(news.logOptions ?? {}).length
+        ? { "log-opt": normalizeLogOptions(news.logOptions) }
+        : {}),
+      ...(news.oomScoreAdjustment !== undefined
+        ? { "oom-score-adj": news.oomScoreAdjustment }
+        : {}),
+      ...(news.stopSignal !== undefined ? { "stop-signal": news.stopSignal } : {}),
+      ...(news.init ? { init: true } : {}),
+      ...(news.user !== undefined ? { user: news.user } : {}),
+      ...(news.tmpfs?.length ? { tmpfs: normalizeTmpfs(news.tmpfs) } : {}),
+      device: normalizeDevices(news.devices),
+      restart: news.restart ?? "no",
+      label: news.labels,
+      "stop-timeout": toSeconds(news.stopTimeout)?.toString(),
+      rm: news.removeOnExit ?? false,
+      ...(news.healthcheck
+        ? {
+            "health-cmd": healthcheckCommand(news.healthcheck.cmd),
+            // Only when set: an always-present key would change every
+            // container's config hash and recreate it on upgrade.
+            ...(isHealthcheckDisabled(news.healthcheck.cmd) ? { "no-healthcheck": true } : {}),
+            "health-interval": normalizeDuration(news.healthcheck.interval),
+            "health-timeout": normalizeDuration(news.healthcheck.timeout),
+            "health-retries": news.healthcheck.retries ?? 0,
+            "health-start-period": normalizeDuration(news.healthcheck.startPeriod),
+            "health-start-interval": normalizeDuration(news.healthcheck.startInterval),
+          }
+        : {
+            "health-cmd": undefined,
+            "health-interval": undefined,
+            "health-timeout": undefined,
+            "health-retries": undefined,
+            "health-start-period": undefined,
+            "health-start-interval": undefined,
+          }),
+    })),
+  );
+
+const toContainerAttributes = (
+  info: Docker.Container,
+  imageRef: string,
+): Container["Attributes"] => ({
+  id: info.Id,
+  name: typeof info.Name === "string" ? info.Name.replace(/^\//, "") : info.Id,
+  status: info.State.Status,
+  createdAt: Date.parse(info.Created) || Date.now(),
+  imageRef,
+  ports: toPortAttributes(info),
+  networkMode: info.HostConfig.NetworkMode,
+  capAdd: info.HostConfig.CapAdd ?? undefined,
+  devices: info.HostConfig.Devices?.map((device) => ({
+    hostPath: device.PathOnHost,
+    containerPath: device.PathInContainer,
+    permissions: device.CgroupPermissions,
+  })),
+});
+
+const normalizeNetworkMode = (mode: Container.NetworkMode | undefined): string | undefined =>
+  mode === undefined ? undefined : typeof mode === "string" ? mode : `container:${mode.container}`;
+
+const normalizeCapabilities = (capAdd: string[] | undefined): string[] | undefined => {
+  if (!capAdd?.length) return undefined;
+  return [...new Set(capAdd.map((capability) => capability.trim()).filter(Boolean))].sort();
+};
+
+const isCustomSeccompProfile = (profile: string | undefined): profile is string =>
+  profile !== undefined && profile !== "builtin" && profile !== "unconfined";
+
+const normalizeSecurityOptions = (props: ContainerProps): string[] | undefined => {
+  const options = [
+    ...(props.noNewPrivileges ? ["no-new-privileges"] : []),
+    ...(props.seccompProfile ? [`seccomp=${props.seccompProfile}`] : []),
+    ...(props.appArmorProfile ? [`apparmor=${props.appArmorProfile}`] : []),
+  ];
+  return options.length ? options : undefined;
+};
+
+const normalizeGroups = (groups: string[]): string[] =>
+  [...new Set(groups.map((group) => group.trim()))].sort();
+
+const normalizeUlimits = (limits: ContainerProps["ulimits"]): string[] =>
+  Object.entries(limits ?? {})
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([name, { soft, hard }]) => `${name}=${soft}:${hard}`);
+
+const normalizeLogOptions = (options: ContainerProps["logOptions"]): string[] =>
+  Object.entries(options ?? {})
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([name, value]) => `${name}=${value}`);
+
+const normalizeTmpfs = (mounts: Container.TmpfsMount[]): string[] =>
+  [...mounts]
+    .sort((a, b) => a.path.localeCompare(b.path))
+    .map(({ path, size, mode }) => {
+      const options = [
+        ...(size !== undefined ? [`size=${size}`] : []),
+        ...(mode !== undefined ? [`mode=${mode.toString(8)}`] : []),
+      ];
+      return options.length > 0 ? `${path}:${options.join(",")}` : path;
+    });
+
+const hasHardeningOptions = (props: ContainerProps): boolean =>
+  (props.capDrop?.length ?? 0) > 0 ||
+  props.memory !== undefined ||
+  props.memorySwap !== undefined ||
+  props.memoryReservation !== undefined ||
+  props.cpus !== undefined ||
+  props.pidsLimit !== undefined ||
+  props.readOnlyRootFilesystem === true ||
+  props.noNewPrivileges === true ||
+  props.seccompProfile !== undefined ||
+  props.appArmorProfile !== undefined ||
+  props.userNamespace !== undefined ||
+  (props.groupAdd?.length ?? 0) > 0 ||
+  Object.keys(props.ulimits ?? {}).length > 0 ||
+  props.logDriver !== undefined ||
+  Object.keys(props.logOptions ?? {}).length > 0 ||
+  props.oomScoreAdjustment !== undefined ||
+  props.stopSignal !== undefined ||
+  props.init === true ||
+  props.user !== undefined ||
+  (props.tmpfs?.length ?? 0) > 0;
+
+const normalizeDevices = (devices: Container.DeviceMapping[] | undefined): string[] | undefined => {
+  if (!devices?.length) return undefined;
+  const normalized = devices.map(
+    (device) => `${device.hostPath}:${device.containerPath}:${device.permissions ?? "rwm"}`,
+  );
+  return [...new Set(normalized)].sort();
+};
+
+/**
+ * Raised before Docker is called when a container's options cannot be
+ * combined, e.g. sharing another container's network namespace while
+ * publishing ports.
+ */
+export class InvalidContainerOptions extends Data.TaggedError("InvalidContainerOptions")<{
+  readonly message: string;
+}> {}
+
+const validateContainerOptions = (news: ContainerProps) => {
+  // The CLI formatter omits empty strings. Reject them instead of silently
+  // dropping user-specified resource and security restrictions.
+  for (const option of [
+    "memory",
+    "memorySwap",
+    "memoryReservation",
+    "user",
+    "seccompProfile",
+    "appArmorProfile",
+    "userNamespace",
+    "logDriver",
+    "stopSignal",
+  ] as const) {
+    if (news[option] !== undefined && news[option].trim().length === 0) {
+      return Effect.fail(
+        new InvalidContainerOptions({
+          message: `Docker.Container ${option} cannot be empty`,
+        }),
+      );
+    }
+  }
+  if (news.capDrop?.some((capability) => capability.trim().length === 0)) {
+    return Effect.fail(
+      new InvalidContainerOptions({
+        message: "Docker.Container capDrop cannot contain empty capabilities",
+      }),
+    );
+  }
+  if (news.groupAdd?.some((group) => group.trim().length === 0)) {
+    return Effect.fail(
+      new InvalidContainerOptions({
+        message: "Docker.Container groupAdd cannot contain empty groups",
+      }),
+    );
+  }
+  for (const [name, limit] of Object.entries(news.ulimits ?? {})) {
+    if (
+      !/^[a-z][a-z0-9_-]*$/.test(name) ||
+      !Number.isSafeInteger(limit.soft) ||
+      !Number.isSafeInteger(limit.hard) ||
+      limit.soft < -1 ||
+      limit.hard < -1 ||
+      (limit.hard !== -1 && (limit.soft === -1 || limit.soft > limit.hard))
+    ) {
+      return Effect.fail(
+        new InvalidContainerOptions({
+          message: `Docker.Container ulimits contains an invalid soft/hard limit for ${name}`,
+        }),
+      );
+    }
+  }
+  for (const [name, value] of Object.entries(news.logOptions ?? {})) {
+    if (!name.trim() || name.includes("=") || !value.trim()) {
+      return Effect.fail(
+        new InvalidContainerOptions({
+          message: `Docker.Container logOptions contains an invalid option: ${name}`,
+        }),
+      );
+    }
+  }
+  if (
+    news.oomScoreAdjustment !== undefined &&
+    (!Number.isInteger(news.oomScoreAdjustment) ||
+      news.oomScoreAdjustment < -1000 ||
+      news.oomScoreAdjustment > 1000)
+  ) {
+    return Effect.fail(
+      new InvalidContainerOptions({
+        message: "Docker.Container oomScoreAdjustment must be an integer from -1000 to 1000",
+      }),
+    );
+  }
+  if (news.memorySwap !== undefined && news.memory === undefined) {
+    return Effect.fail(
+      new InvalidContainerOptions({
+        message: "Docker.Container memorySwap requires memory to be set",
+      }),
+    );
+  }
+  if (news.cpus !== undefined && (!Number.isFinite(news.cpus) || news.cpus <= 0)) {
+    return Effect.fail(
+      new InvalidContainerOptions({
+        message: "Docker.Container cpus must be a finite, positive number",
+      }),
+    );
+  }
+  if (
+    news.pidsLimit !== undefined &&
+    (!Number.isInteger(news.pidsLimit) || (news.pidsLimit <= 0 && news.pidsLimit !== -1))
+  ) {
+    return Effect.fail(
+      new InvalidContainerOptions({
+        message: "Docker.Container pidsLimit must be a positive integer or -1 (unlimited)",
+      }),
+    );
+  }
+  if (
+    isContainerNetworkMode(news.networkMode) &&
+    ((news.ports?.length ?? 0) > 0 || (news.networks?.length ?? 0) > 0)
+  ) {
+    return Effect.fail(
+      new InvalidContainerOptions({
+        message: "Docker.Container networkMode.container cannot be combined with ports or networks",
+      }),
+    );
+  }
+  const targets = new Set<string>();
+  for (const device of news.devices ?? []) {
+    if (targets.has(device.containerPath)) {
+      return Effect.fail(
+        new InvalidContainerOptions({
+          message: `Docker.Container devices contain conflicting target path ${device.containerPath}`,
+        }),
+      );
+    }
+    targets.add(device.containerPath);
+  }
+  const tmpfsTargets = new Set<string>();
+  for (const mount of news.tmpfs ?? []) {
+    if (mount.size !== undefined && mount.size.trim().length === 0) {
+      return Effect.fail(
+        new InvalidContainerOptions({
+          message: `Docker.Container tmpfs size cannot be empty for ${mount.path}`,
+        }),
+      );
+    }
+    if (!mount.path.startsWith("/") || mount.path.includes(":") || mount.path.includes(",")) {
+      return Effect.fail(
+        new InvalidContainerOptions({
+          message: `Docker.Container tmpfs target must be an absolute path: ${mount.path}`,
+        }),
+      );
+    }
+    if (tmpfsTargets.has(mount.path)) {
+      return Effect.fail(
+        new InvalidContainerOptions({
+          message: `Docker.Container tmpfs contains duplicate target ${mount.path}`,
+        }),
+      );
+    }
+    if (
+      mount.mode !== undefined &&
+      (!Number.isInteger(mount.mode) || mount.mode < 0 || mount.mode > 0o7777)
+    ) {
+      return Effect.fail(
+        new InvalidContainerOptions({
+          message: `Docker.Container tmpfs mode is not a valid POSIX mode for ${mount.path}`,
+        }),
+      );
+    }
+    tmpfsTargets.add(mount.path);
+  }
+  return Effect.void;
+};
+
+const isContainerNetworkMode = (mode: Container.NetworkMode | undefined): boolean =>
+  typeof mode === "string" ? mode.startsWith("container:") : mode !== undefined;
+
+/** First binding that carries a real (non-zero) host port. */
+const boundHostPort = (
+  bindings: ReadonlyArray<{ HostPort?: string }> | null | undefined,
+): number | undefined => {
+  for (const binding of bindings ?? []) {
+    if (!binding.HostPort) continue;
+    const port = Number.parseInt(binding.HostPort, 10);
+    if (Number.isInteger(port) && port > 0) return port;
+  }
+  return undefined;
+};
+
+/**
+ * `HostConfig.PortBindings` is what was *requested*, `NetworkSettings.Ports`
+ * what Docker actually *assigned* — so the assignment wins wherever both
+ * exist. A container published with `external: 0` (or any random-publish
+ * mapping) has no requested host port at all, and reading the request over
+ * the assignment reported 0 instead of the port the container is reachable
+ * on. The request is still the fallback: a created-but-not-yet-started
+ * container has empty `NetworkSettings.Ports`.
+ */
+const toPortAttributes = (info: Docker.Container): Record<string, number> => {
+  const ports: Record<string, number> = {};
+  for (const [internal, bindings] of Object.entries(info.HostConfig.PortBindings ?? {})) {
+    const port = boundHostPort(bindings);
+    if (port !== undefined) ports[internal] = port;
+  }
+  for (const [internal, bindings] of Object.entries(info.NetworkSettings.Ports ?? {})) {
+    const port = boundHostPort(bindings);
+    if (port !== undefined) ports[internal] = port;
+  }
+  return ports;
+};
+
+/** `external: 0` / `"0"` asks Docker to pick any free host port. */
+const isRandomHostPort = (external: number | string): boolean =>
+  Number.parseInt(String(external), 10) === 0;
+
+const normalizeEnvironment = (
+  environment: Record<string, string | Redacted.Redacted<string>> | undefined,
+): Record<string, string> =>
+  Object.fromEntries(
+    Object.entries(environment ?? {}).map(([key, value]) => [
+      key,
+      Redacted.isRedacted(value) ? Redacted.value(value) : value,
+    ]),
+  );
+
+const normalizeDuration = (input: Duration.Input | undefined): string | undefined => {
+  if (!input) return undefined;
+  const duration = Duration.fromInputUnsafe(input);
+  // Docker parses `--health-*` durations with Go's `time.ParseDuration`, which
+  // requires a unit suffix — a bare nanosecond count is rejected with "missing
+  // unit in duration". `ns` is the lossless Go-duration rendering of the nanos.
+  return `${Duration.toNanosUnsafe(duration).toString()}ns`;
+};