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

package/src/Container.ts

@@ -0,0 +1,792 @@
+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[];
+  /** 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 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:** 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"));
+      });
+
+      // 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);
+        return yield* sha256Object({
+          ...args,
+          imageId: normalizeImageId(news.image),
+          ...(envFiles === undefined ? {} : { envFiles }),
+        });
+      });
+
+      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 };
+          }
+          // Same env file paths, possibly new contents: compare against the
+          // hash stamped on the running container.
+          if (news.envFiles?.length) {
+            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
+              : 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),
+      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 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) => {
+  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);
+  }
+  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`;
+};