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`;
};