import { createPhysicalName } from "alchemy/PhysicalName";
import type { ScopedPlanStatusSession } from "alchemy/Report";
import * as Config from "effect/Config";
import * as Context from "effect/Context";
import * as Effect from "effect/Effect";
import { Base64 } from "effect/encoding";
import * as FileSystem from "effect/FileSystem";
import { flow } from "effect/Function";
import * as Layer from "effect/Layer";
import * as Option from "effect/Option";
import * as Path from "effect/Path";
import { PlatformError, SystemError, type SystemErrorTag } from "effect/PlatformError";
import * as ChildProcess from "effect/process/ChildProcess";
import * as ChildProcessSpawner from "effect/process/ChildProcessSpawner";
import * as Redacted from "effect/Redacted";
import * as Result from "effect/Result";
import * as Schema from "effect/Schema";
import * as Sink from "effect/Sink";
import * as Stream from "effect/Stream";
import { classifyDockerRegistryError, type DockerImagePublicationError } from "./RegistryError.ts";
/** Credentials for a single image registry, scoped to a Docker command. */
export interface RegistryCredentials {
/** Registry hostname, without a URL scheme. */
server: string;
/** Registry authentication username. */
username: string;
/** Registry password or access token. */
password: string | Redacted.Redacted<string>;
}
const RegistryAuth = Schema.String.pipe(
Schema.check(
Schema.makeFilter((value) => {
const decoded = Base64.decode(value);
return Result.isSuccess(decoded) && decoded.success.indexOf(58) > 0;
}),
),
);
const decodeRegistryAuthConfig = Schema.Struct({
auths: Schema.Record(Schema.String, Schema.Struct({ auth: RegistryAuth })).pipe(
Schema.NullOr,
Schema.optional,
),
}).pipe(Schema.fromJsonString, (schema) =>
Schema.decodeEffect(schema, { onExcessProperty: "error" }),
);
export class Docker extends Context.Service<
Docker,
{
/** Runs a Docker command and returns the output. Use this to run a command that doesn't have a dedicated method. */
readonly run: (args: Array<string>) => Effect.Effect<CommandOutput, PlatformError>;
/** Writes build files and an inline Dockerfile to the given context directory. */
readonly materialize: (options: {
context: string;
dockerfile: string;
files: ReadonlyArray<{ path: string; content: string | Uint8Array }>;
}) => Effect.Effect<void, PlatformError>;
readonly container: {
/** Creates a new container. */
readonly create: (options: {
name: string;
image: string;
volume: Array<string> | undefined;
env: Record<string, string> | undefined;
/** Paths to Docker env files, forwarded as repeated `--env-file`. */
"env-file"?: Array<string> | undefined;
restart: "no" | "always" | "on-failure" | "unless-stopped";
rm: boolean;
"health-cmd": string | undefined;
/** `--no-healthcheck`: disable any healthcheck defined by the image. */
"no-healthcheck"?: boolean;
"health-interval": string | undefined;
"health-timeout": string | undefined;
"health-retries": number | undefined;
"health-start-period": string | undefined;
"health-start-interval": string | undefined;
"stop-timeout": string | undefined;
p: Array<string> | undefined;
/** `--add-host` entries, each `hostname:address`. */
"add-host"?: Array<string> | undefined;
/** Docker network namespace, including `container:<id>`. */
network?: string | undefined;
/** Linux capabilities to add. */
"cap-add"?: Array<string> | undefined;
/** Linux capabilities to drop. */
"cap-drop"?: Array<string> | undefined;
/** Hard memory limit in Docker's byte-suffix format. */
memory?: string | undefined;
/** Combined memory-and-swap limit in Docker's byte-suffix format. */
"memory-swap"?: string | undefined;
/** Soft memory reservation for memory contention. */
"memory-reservation"?: string | undefined;
/** CPU quota, in cores. */
cpus?: number | undefined;
/** Per-container process and thread limit. */
"pids-limit"?: number | undefined;
/** Mount the root filesystem read-only. */
"read-only"?: boolean | undefined;
/** Security options such as `no-new-privileges` and seccomp/AppArmor profiles. */
"security-opt"?: Array<string> | undefined;
/** Per-container user namespace; "host" disables daemon user remapping. */
userns?: string | undefined;
/** Supplemental Linux groups. */
"group-add"?: Array<string> | undefined;
/** Per-process soft/hard resource limits. */
ulimit?: Array<string> | undefined;
/** Docker log driver. */
"log-driver"?: string | undefined;
/** Driver-specific Docker logging options. */
"log-opt"?: Array<string> | undefined;
/** Kernel OOM score adjustment. */
"oom-score-adj"?: number | undefined;
/** Signal used on container stop. */
"stop-signal"?: string | undefined;
/** Run Docker's tiny init process. */
init?: boolean | undefined;
/** Runtime UID/GID or named user. */
user?: string | undefined;
/** Docker tmpfs mount expressions (target[:options]). */
tmpfs?: Array<string> | undefined;
/** Host devices in Docker's `host:container[:permissions]` form. */
device?: Array<string> | undefined;
command: Array<string> | undefined;
label?: Record<string, string>;
context?: string;
}) => Effect.Effect<CommandOutput, PlatformError>;
/** Inspects a container. */
readonly inspect: (
name: string,
context?: string,
) => Effect.Effect<Docker.Container, PlatformError>;
/** Removes a container. */
readonly remove: (
name: string,
force?: boolean,
context?: string,
) => Effect.Effect<CommandOutput, PlatformError>;
/** Starts a container. */
readonly start: (
name: string,
context?: string,
) => Effect.Effect<CommandOutput, PlatformError>;
/** Stops a container. */
readonly stop: (
name: string,
context?: string,
) => Effect.Effect<CommandOutput, PlatformError>;
};
readonly image: {
/**
* Builds locally, or publishes to a registry when credentials are
* supplied. With Buildx 0.26.0 or newer the image is exported straight
* from BuildKit (`buildx build --push`); older plugins build into the
* local image store and then `push`. If a session is provided, build
* logs will be emitted as session notes.
*/
readonly build: (
options: {
context: string;
/** Image tags to build and publish together. */
tag: string | [string, ...string[]];
file?: string;
platform?: string;
target?: string;
"build-arg"?: Record<string, string>;
/**
* BuildKit secrets, keyed by id (`RUN --mount=type=secret,id=<id>`).
* Values reach `docker` through its environment, never its argv,
* and are not written to the image.
*/
secrets?: Record<string, string | Redacted.Redacted<string>>;
"cache-from"?: Array<string>;
"cache-to"?: Array<string>;
args?: Array<string>;
engineContext?: string;
/** Registry auth for the build itself (base images, caches); publishes nothing. */
credentials?: RegistryCredentials;
},
session?: ScopedPlanStatusSession,
registry?: RegistryCredentials,
) => Effect.Effect<CommandOutput, DockerImagePublicationError>;
/** Pulls an image. */
readonly pull: (
ref: string,
platform?: string,
context?: string,
session?: Pick<ScopedPlanStatusSession, "note">,
) => Effect.Effect<CommandOutput, PlatformError>;
/**
* Pushes an image to a registry. When `platform` is given, only that
* platform's manifest is pushed (`docker push --platform`) — with the
* containerd image store, a bare push sends every locally-present
* variant of a multi-arch tag, so a stale other-arch variant in the
* local cache would otherwise reach the registry. Engines whose store
* doesn't support the flag fall back to a plain push (their local tag
* is already narrowed by `pull --platform`).
*/
readonly push: (
ref: string,
credentials: RegistryCredentials,
platform?: string,
context?: string,
session?: Pick<ScopedPlanStatusSession, "note">,
) => Effect.Effect<CommandOutput, DockerImagePublicationError>;
/** Tags an image. */
readonly tag: (
source: string,
target: string,
context?: string,
) => Effect.Effect<CommandOutput, PlatformError>;
/** Inspects an image. */
readonly inspect: (
ref: string,
context?: string,
) => Effect.Effect<Docker.Image, PlatformError>;
/** Removes an image. */
readonly remove: (
ref: string | Array<string>,
force?: boolean,
context?: string,
) => Effect.Effect<CommandOutput, PlatformError>;
};
readonly volume: {
/** Creates a new volume. */
readonly create: (options: {
name: string;
driver?: string;
opt?: Record<string, string>;
label?: Record<string, string>;
context?: string;
}) => Effect.Effect<CommandOutput, PlatformError>;
/** Removes a volume. */
readonly remove: (
name: string,
context?: string,
) => Effect.Effect<CommandOutput, PlatformError>;
/** Inspects a volume. */
readonly inspect: (
name: string,
context?: string,
) => Effect.Effect<Docker.Volume, PlatformError>;
};
readonly context: {
/** Creates a new Docker context. */
readonly create: (options: {
name: string;
description?: string;
/** Raw value for `--docker`, for example `host=ssh://user@host`. */
docker?: string;
}) => Effect.Effect<CommandOutput, PlatformError>;
/** Updates an existing Docker context. */
readonly update: (options: {
name: string;
description?: string;
/** Raw value for `--docker`, for example `host=ssh://user@host`. */
docker?: string;
}) => Effect.Effect<CommandOutput, PlatformError>;
/** Inspects a Docker context. */
readonly inspect: (name: string) => Effect.Effect<Docker.Context, PlatformError>;
/** Removes a Docker context. */
readonly remove: (
name: string,
force?: boolean,
) => Effect.Effect<CommandOutput, PlatformError>;
};
readonly network: {
/** Creates a new network. */
readonly create: (options: {
name: string;
driver: string;
ipv6?: boolean;
label?: Record<string, string>;
context?: string;
}) => Effect.Effect<CommandOutput, PlatformError>;
/** Connects a container to a network. */
readonly connect: (options: {
network: string;
container: string;
alias?: string[];
context?: string;
}) => Effect.Effect<CommandOutput, PlatformError>;
/** Disconnects a container from a network. */
readonly disconnect: (options: {
network: string;
container: string;
context?: string;
}) => Effect.Effect<CommandOutput, PlatformError>;
/** Inspects a network. */
readonly inspect: (
name: string,
context?: string,
) => Effect.Effect<Docker.Network, PlatformError>;
/** Removes a network. */
readonly remove: (
id: string,
context?: string,
) => Effect.Effect<CommandOutput, PlatformError>;
};
readonly swarm: {
/** Initializes swarm mode on the engine (`docker swarm init`). */
readonly init: (options: {
context?: string;
"advertise-addr"?: string;
"listen-addr"?: string;
"default-addr-pool"?: string[];
"default-addr-pool-mask-length"?: number;
}) => Effect.Effect<CommandOutput, PlatformError>;
/** Reads the engine's swarm state (`docker info --format '{{json .Swarm}}'`). */
readonly info: (context?: string) => Effect.Effect<Docker.SwarmInfo, PlatformError>;
/** Leaves the swarm (`docker swarm leave`). */
readonly leave: (
force?: boolean,
context?: string,
) => Effect.Effect<CommandOutput, PlatformError>;
};
readonly service: {
/** Creates a new service. */
readonly create: (options: {
name: string;
image: string;
context?: string;
replicas?: number;
"endpoint-mode"?: "vip" | "dnsrr";
network?: string[];
constraint?: string[];
"replicas-max-per-node"?: number;
"placement-pref"?: string[];
"update-parallelism"?: number;
"update-delay"?: string;
"update-monitor"?: string;
"update-failure-action"?: "pause" | "continue" | "rollback";
"update-max-failure-ratio"?: number;
"update-order"?: "stop-first" | "start-first";
"rollback-parallelism"?: number;
"rollback-delay"?: string;
"rollback-monitor"?: string;
"rollback-failure-action"?: "pause" | "continue" | "rollback";
"rollback-max-failure-ratio"?: number;
"rollback-order"?: "stop-first" | "start-first";
"restart-condition"?: "none" | "on-failure" | "any";
"restart-delay"?: string;
"restart-max-attempts"?: number;
"restart-window"?: string;
"health-cmd"?: string;
/** `--no-healthcheck`: disable any healthcheck defined by the image. */
"no-healthcheck"?: boolean;
"health-interval"?: string;
"health-timeout"?: string;
"health-retries"?: number;
"health-start-period"?: string;
"stop-grace-period"?: string;
mount?: string[];
secret?: string[];
config?: string[];
"read-only"?: boolean;
publish?: string[];
label?: Record<string, string>;
env?: Record<string, string>;
command?: string[];
args?: string[];
}) => Effect.Effect<CommandOutput, PlatformError>;
/** Updates an existing service. */
readonly update: (options: {
id: string;
image: string;
context?: string;
replicas?: number;
"endpoint-mode"?: "vip" | "dnsrr";
/** Networks to detach, by name or id; applied before `network-add`. */
"network-rm"?: string[];
"network-add"?: string[];
"constraint-add"?: string[];
"constraint-rm"?: string[];
"replicas-max-per-node"?: number;
"update-parallelism"?: number;
"update-delay"?: string;
"update-monitor"?: string;
"update-failure-action"?: "pause" | "continue" | "rollback";
"update-max-failure-ratio"?: number;
"update-order"?: "stop-first" | "start-first";
"rollback-parallelism"?: number;
"rollback-delay"?: string;
"rollback-monitor"?: string;
"rollback-failure-action"?: "pause" | "continue" | "rollback";
"rollback-max-failure-ratio"?: number;
"rollback-order"?: "stop-first" | "start-first";
"restart-condition"?: "none" | "on-failure" | "any";
"restart-delay"?: string;
"restart-max-attempts"?: number;
"restart-window"?: string;
"health-cmd"?: string;
/** `--no-healthcheck`: disable any healthcheck defined by the image. */
"no-healthcheck"?: boolean;
"health-interval"?: string;
"health-timeout"?: string;
"health-retries"?: number;
"health-start-period"?: string;
"stop-grace-period"?: string;
"mount-add"?: string[];
/** Mount targets to remove. */
"mount-rm"?: string[];
"secret-add"?: string[];
/** Secret names to remove; applied before `secret-add`. */
"secret-rm"?: string[];
"config-add"?: string[];
/** Config names to remove; applied before `config-add`. */
"config-rm"?: string[];
"read-only"?: boolean;
"publish-add"?: string[];
/** Published ports to remove, as `target=<port>,protocol=<p>,mode=<m>`. */
"publish-rm"?: string[];
"label-add"?: Record<string, string>;
"label-rm"?: string[];
"env-add"?: Record<string, string>;
/** Environment variable names to remove. */
"env-rm"?: string[];
args?: string;
}) => Effect.Effect<CommandOutput, PlatformError>;
/** Inspects a service. */
readonly inspect: (
id: string,
context?: string,
) => Effect.Effect<CommandOutput, PlatformError>;
/** Removes a service. */
readonly remove: (
id: string,
context?: string,
) => Effect.Effect<CommandOutput, PlatformError>;
};
}
>()("@alchemy/Docker") {}
export declare namespace Docker {
export type ContextRef = string | { name: string };
/**
* A reference to the Docker engine an operation runs against: a context
* name, a `Docker.Context` resource, or a `Docker.Swarm` resource
* (narrowed structurally by its `nodeId` attribute) — passing the swarm
* also orders the operation after the swarm is initialized.
*/
export type EngineRef = ContextRef | { nodeId: string; context?: string };
export interface SwarmInfo {
NodeID: string;
LocalNodeState: "inactive" | "pending" | "active" | "error" | "locked" | (string & {});
ControlAvailable: boolean;
Cluster?: { ID: string; CreatedAt?: string } | null;
RemoteManagers?: Array<{ NodeID: string; Addr: string }> | null;
Managers?: number;
Nodes?: number;
}
export type ContainerStatus =
| "created"
| "running"
| "paused"
| "restarting"
| "removing"
| "exited"
| "dead";
export interface Container {
Id: string;
Image: string;
Name?: string;
State: {
Status: ContainerStatus;
/** Present when the container has a healthcheck. */
Health?: { Status: "starting" | "healthy" | "unhealthy" };
};
Created: string;
Config: {
Image: string;
Cmd: string[] | null;
Env: string[] | null;
User?: string;
StopSignal?: string;
Labels: Record<string, string> | null;
StopTimeout?: number;
Healthcheck?: {
Test: string[] | null;
Interval?: number;
Timeout?: number;
Retries?: number;
StartPeriod?: number;
StartInterval?: number;
} | null;
};
HostConfig: {
PortBindings: Record<string, Array<{ HostIp: string; HostPort: string }> | null> | null;
Binds: string[] | null;
ExtraHosts: string[] | null;
RestartPolicy: { Name: string; MaximumRetryCount: number };
AutoRemove: boolean;
NetworkMode?: string;
CapAdd?: string[] | null;
CapDrop?: string[] | null;
Memory?: number;
MemorySwap?: number;
MemoryReservation?: number;
NanoCpus?: number;
PidsLimit?: number;
ReadonlyRootfs?: boolean;
SecurityOpt?: string[] | null;
UsernsMode?: string;
GroupAdd?: string[] | null;
Ulimits?: Array<{ Name: string; Soft: number; Hard: number }> | null;
LogConfig?: { Type: string; Config: Record<string, string> | null };
OomScoreAdj?: number;
Init?: boolean | null;
Tmpfs?: Record<string, string> | null;
Devices?: Array<{
PathOnHost: string;
PathInContainer: string;
CgroupPermissions: string;
}> | null;
};
AppArmorProfile?: string;
NetworkSettings: {
Networks: Record<string, { NetworkID: string; Aliases: string[] | null }> | null;
Ports?: Record<string, Array<{ HostIp: string; HostPort: string }> | null> | null;
};
}
export interface Image {
Id: string;
Created?: string;
RepoTags?: string[] | null;
RepoDigests?: string[] | null;
}
export interface Volume {
CreatedAt: string;
Driver: string;
Labels: Record<string, string> | null;
Mountpoint: string;
Name: string;
Options: Record<string, string> | null;
Scope: string;
}
export interface Context {
Name: string;
Metadata?: { Description?: string };
Endpoints?: { docker?: string };
}
export interface Network {
Name: string;
Id: string;
Created: string;
Scope: string;
Driver: string;
EnableIPv6: boolean;
Labels: Record<string, string> | null;
}
}
export interface CommandOutput {
exitCode: ChildProcessSpawner.ExitCode;
stdout: string;
stderr: string;
}
export interface DockerOptions {
/**
* The Docker-compatible CLI to run, e.g. `"podman"`. The `DOCKER_BIN`
* environment variable, when set, overrides it (per machine or CI).
* @default "docker"
*/
bin?: string;
}
/**
* Extra environment for every Docker CLI invocation, layered over the
* process environment (per-call variables still win). Scope it with
* `Effect.provideService(DockerEnvironment, { BUILDX_BUILDER: "ci" })` to
* target a buildx builder or Docker context without mutating `process.env`.
* @default {}
*/
export const DockerEnvironment = Context.Reference<Record<string, string>>(
"alchemy/Docker/DockerEnvironment",
{ defaultValue: () => ({}) },
);
/** The Docker CLI client, running `options.bin` (`DOCKER_BIN` overrides). */
export const dockerLive = (options: DockerOptions = {}) =>
Layer.effect(Docker, makeDocker(options));
const makeDocker = (options: DockerOptions) =>
Effect.gen(function* () {
const fs = yield* FileSystem.FileSystem;
const path = yield* Path.Path;
const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
const bin = yield* Config.String("DOCKER_BIN").pipe(
Effect.orElseSucceed(() => options.bin ?? "docker"),
);
const run = (
args: Array<string>,
env?: Record<string, string>,
tap: (
stream: Stream.Stream<string, PlatformError, never>,
) => Stream.Stream<string, PlatformError, never> = Stream.tap(Effect.logDebug),
) =>
Effect.gen(function* () {
const ambient = yield* DockerEnvironment;
return yield* spawner.spawn(
ChildProcess.make(bin, args, {
stdin: "ignore",
stdout: "pipe",
stderr: "pipe",
detached: false,
env: { ...ambient, ...env },
extendEnv: true,
}),
);
}).pipe(
Effect.flatMap((child) =>
Effect.all(
{
exitCode: child.exitCode,
stdout: child.stdout.pipe(
Stream.decodeText,
tap,
Stream.mkString,
Effect.map((stdout) => stdout.trim()),
),
stderr: child.stderr.pipe(
Stream.decodeText,
tap,
Stream.mkString,
Effect.map((stderr) => stderr.trim()),
),
},
{ concurrency: "unbounded" },
),
),
Effect.mapError((error) =>
systemError({
_tag: "Unknown",
args,
// Name the CLI: a misconfigured `bin` / DOCKER_BIN fails here.
description: `Failed to run \`${bin}\`; is it installed and on PATH?`,
cause: error.reason,
}),
),
Effect.tap((result) => {
if (result.exitCode === 0) return Effect.void;
const stderr = result.stderr.replace(/^Error response from daemon: /, "");
if (stderr.match(/not found|not known|no such/i)) {
return systemError({ _tag: "NotFound", args, description: stderr });
}
if (stderr.match(/already exists/i)) {
return systemError({ _tag: "AlreadyExists", args, description: stderr });
}
return systemError({
_tag: "Unknown",
args,
description: `Command exited with code ${result.exitCode}: ${failureOutput(
stderr,
result.stdout,
)}`,
});
}),
Effect.scoped,
);
const runInspect = <T>(args: Array<string>) =>
run(args).pipe(
Effect.map((result) => {
const [item] = JSON.parse(result.stdout) as T[];
return item;
}),
);
// Merge `credentials` into the ambient auth config: the process's
// DOCKER_AUTH_CONFIG, overlaid by one provided through DockerEnvironment
// (as `run` layers DockerEnvironment over the process environment).
// Merging, not replacing, keeps the user's own registry logins.
const registryEnvironment = Effect.fn("registryEnvironment")(
(credentials: RegistryCredentials) =>
Effect.gen(function* () {
const value = yield* Config.Redacted("DOCKER_AUTH_CONFIG").pipe(
Config.withDefault(Redacted.make("{}")),
);
const base = yield* decodeRegistryAuthConfig(Redacted.value(value) || "{}");
const ambient = yield* DockerEnvironment;
const overlay =
ambient.DOCKER_AUTH_CONFIG === undefined
? undefined
: yield* decodeRegistryAuthConfig(ambient.DOCKER_AUTH_CONFIG || "{}");
return { auths: { ...base.auths, ...overlay?.auths } };
}).pipe(
// Schema diagnostics may include credential input. Do not retain them.
Effect.mapError(() =>
systemError({
_tag: "InvalidData",
args: ["buildx", "build"],
description: "Invalid DOCKER_AUTH_CONFIG; expected an auths map.",
}),
),
Effect.map((current) => {
const password = Redacted.isRedacted(credentials.password)
? Redacted.value(credentials.password)
: credentials.password;
const auth = Base64.encode(`${credentials.username}:${password}`);
// Preserve Docker's file/helper fallback, contexts, and builders.
return {
DOCKER_AUTH_CONFIG: JSON.stringify({
auths: { ...current.auths, [credentials.server]: { auth } },
}),
};
}),
),
);
// How a build reaches a registry. Buildx 0.26 is the first release
// embedding Docker CLI 28.3's DOCKER_AUTH_CONFIG credential store, so it
// can `buildx build --push` straight from BuildKit. Older plugins (e.g.
// the buildx bundled with Docker Desktop < 4.44) silently ignore the
// variable, so the image is instead `--load`ed into the local store and
// published with the isolated-config `push`. Without any buildx plugin
// the legacy builder always loads, so a plain `image build` suffices.
// Probed once per Docker service instance.
const publication = yield* Effect.cached(
Effect.gen(function* () {
const version = yield* run(["buildx", "version"]).pipe(Effect.option);
if (Option.isNone(version)) return "legacy" as const;
// Numeric template captures can consume version separators as decimals.
const match =
/^github\.com\/docker\/buildx v?(\d+)\.(\d+)\.\d+(?:[-+][^\s]+)?(?:\s.*)?$/.exec(
version.value.stdout,
);
if (!match) return "load" as const;
const major = Number(match[1]);
const minor = Number(match[2]);
return major >= 1 || minor >= 26 ? ("export" as const) : ("load" as const);
}),
);
const outputTap = (session?: Pick<ScopedPlanStatusSession, "note">) =>
session
? Stream.tapSink(
Sink.make<string>()(
flow(
Stream.splitLines,
Stream.runForEach((line) => session.note(line, { kind: "output" })),
),
),
)
: undefined;
// `podman push` prints no `digest:` line, and Podman's RepoDigests can
// list a source digest under the pushed name, so Podman pushes report the
// published digest through `--digestfile` instead. Probed once.
const isPodman = yield* Effect.cached(
run(["--version"]).pipe(
Effect.map((result) => /^podman\b/i.test(result.stdout.trim())),
Effect.orElseSucceed(() => false),
),
);
const push: Docker["Service"]["image"]["push"] = Effect.fn(
function* (ref, credentials, platform, context, session) {
// Write the registry credentials directly into an isolated docker config
// as a plaintext `auths` entry and skip `docker login` entirely.
//
// `docker login` is the wrong tool here: on macOS Docker Desktop it routes
// through the shared `osxkeychain`/`desktop` credential helper *regardless*
// of an isolated DOCKER_CONFIG, so concurrent deploys either race the system
// keychain (`The specified item already exists in the keychain (-25299)`) or
// land the credential in the helper — leaving this isolated config without
// an `auths` entry, so the subsequent `docker push` fails with "no basic
// auth credentials". Embedding the base64 `auth` inline (the same thing
// `docker login` would write when no credsStore is configured) makes each
// deploy fully self-contained: no credential helper, no keychain, no login
// race. Only `push` reads this config; `build`/`pull`/`tag` keep using the
// global docker config (buildx builders, `docker context`, etc. intact).
const dir = yield* fs.makeTempDirectoryScoped({ prefix: "alchemy-docker-" });
// The isolated DOCKER_CONFIG holds none of the CLI's contexts. Ask the CLI
// (same environment as the push) which context it would use, and copy just
// that context's metadata and TLS material in.
const selected =
context ??
(yield* run(["context", "show"]).pipe(
Effect.map((result) => result.stdout),
Effect.orElseSucceed(() => "default"),
));
if (selected && selected !== "default") {
const inspected = yield* runInspect<{
Storage: { MetadataPath: string; TLSPath: string };
}>(["context", "inspect", selected]);
for (const [kind, source] of [
["meta", inspected.Storage.MetadataPath],
["tls", inspected.Storage.TLSPath],
] as const) {
if (!(yield* fs.exists(source))) continue;
const target = path.join(dir, "contexts", kind, path.basename(source));
yield* fs.makeDirectory(path.dirname(target), { recursive: true });
yield* fs.copy(source, target);
}
}
const pushContext = selected && selected !== "default" ? selected : context;
const config = yield* Effect.sync(() => {
const password = Redacted.isRedacted(credentials.password)
? Redacted.value(credentials.password)
: credentials.password;
const auth = Buffer.from(`${credentials.username}:${password}`).toString("base64");
return JSON.stringify({ auths: { [credentials.server]: { auth } } });
});
yield* fs.writeFileString(path.join(dir, "config.json"), config);
const digestFile = path.join(dir, "digest");
const digestArgs = (yield* isPodman) ? ["--digestfile", digestFile] : [];
const result =
platform === undefined
? yield* run(
[...formatArgs({ context: pushContext }), "push", ...digestArgs, ref],
{ DOCKER_CONFIG: dir },
outputTap(session),
)
: yield* run(
[
...formatArgs({ context: pushContext }),
"push",
"--platform",
platform,
...digestArgs,
ref,
],
{ DOCKER_CONFIG: dir },
outputTap(session),
).pipe(
// Engines without the containerd image store reject `--platform`
// on push; their local tag is already narrowed to the requested
// platform by `pull --platform`, so a plain push is equivalent.
Effect.catchIf(
(error) => /--platform|unknown flag|containerd/i.test(String(error)),
() =>
run(
[...formatArgs({ context: pushContext }), "push", ...digestArgs, ref],
{ DOCKER_CONFIG: dir },
outputTap(session),
),
),
);
if (digestArgs.length === 0) return result;
const digest = (yield* fs
.readFileString(digestFile)
.pipe(Effect.orElseSucceed(() => ""))).trim();
// Report it the way `docker push` does, so callers parse one format.
return digest ? { ...result, stdout: `${result.stdout}\ndigest: ${digest}` } : result;
},
Effect.scoped,
Effect.mapError(classifyDockerRegistryError),
);
return Docker.of({
run,
materialize: Effect.fn((options) =>
Effect.forEach(
[...options.files, { path: "Dockerfile", content: options.dockerfile }],
(file) => {
const fullPath = path.join(options.context, file.path);
return fs
.makeDirectory(path.dirname(fullPath), { recursive: true })
.pipe(
Effect.andThen(
typeof file.content === "string"
? fs.writeFileString(fullPath, file.content)
: fs.writeFile(fullPath, file.content),
),
);
},
{ concurrency: "unbounded" },
),
),
container: {
create: ({ image, env, command, context, ...options }) =>
// `--env KEY` (name-only) keeps values off CLI arguments; Docker
// copies each value from the CLI process environment, so the
// normalized container env must be passed to the child process.
run(
[
...formatArgs({ context }),
"container",
"create",
...formatArgs({ ...options, env: env ? Object.keys(env) : undefined }),
image,
...(command ?? []),
],
env,
),
inspect: (name, context) =>
runInspect<Docker.Container>([...formatArgs({ context }), "container", "inspect", name]),
remove: (name, force, context) =>
run([...formatArgs({ context }), "container", "rm", name, ...(force ? ["-f"] : [])]),
start: (name, context) => run([...formatArgs({ context }), "container", "start", name]),
stop: (name, context) => run([...formatArgs({ context }), "container", "stop", name]),
},
image: {
build: Effect.fn("Docker.image.build")(function* (
{ context: buildContext, engineContext, args, credentials, secrets, ...options },
session,
registry,
) {
const tap = outputTap(session);
const secret = buildSecrets(secrets);
const buildArgs = [buildContext, ...formatArgs(options), ...secret.args, ...(args ?? [])];
const engine = formatArgs({ context: engineContext });
if (registry === undefined) {
return yield* run(
[...engine, "image", "build", ...buildArgs],
{
...(credentials ? yield* registryEnvironment(credentials) : undefined),
...secret.env,
},
tap,
);
}
const mode = yield* publication;
if (mode === "export") {
// Export straight from BuildKit to the registry; the image never
// round-trips through the local image store.
const env = yield* registryEnvironment(registry);
return yield* run(
[...engine, "buildx", "build", "--push", ...buildArgs],
{ ...env, ...secret.env },
tap,
).pipe(Effect.mapError(classifyDockerRegistryError));
}
// Older Buildx ignores DOCKER_AUTH_CONFIG, so a `--push` export
// would fail with "no basic auth credentials". Build into the local
// store and publish with the isolated-config `push` instead.
// `--load` matters for non-loading builders (docker-container):
// without it the result stays in the build cache and `push` sees no
// such tag.
yield* run(
[
...engine,
...(mode === "load" ? ["buildx", "build", "--load"] : ["image", "build"]),
...buildArgs,
],
secret.env,
tap,
);
const [tag, ...tags] =
typeof options.tag === "string" ? ([options.tag] as const) : options.tag;
return yield* push(tag, registry, options.platform, engineContext, session).pipe(
Effect.tap(() =>
Effect.forEach(tags, (tag) =>
push(tag, registry, options.platform, engineContext, session),
),
),
);
}),
pull: (ref, platform, context, session) =>
run(
[
...formatArgs({ context }),
"image",
"pull",
ref,
...(platform ? ["--platform", platform] : []),
],
undefined,
outputTap(session),
),
inspect: (ref, context) =>
runInspect<Docker.Image>([...formatArgs({ context }), "image", "inspect", ref]),
remove: (ref, force, context) =>
run([
...formatArgs({ context }),
"image",
"rm",
...(Array.isArray(ref) ? ref : [ref]),
...(force ? ["-f"] : []),
]),
tag: (source, target, context) =>
run([...formatArgs({ context }), "image", "tag", source, target]),
push,
},
volume: {
create: ({ context, ...options }) =>
run([...formatArgs({ context }), "volume", "create", ...formatArgs(options)]),
remove: (name, context) => run([...formatArgs({ context }), "volume", "rm", name]),
inspect: (name, context) =>
runInspect<Docker.Volume>([...formatArgs({ context }), "volume", "inspect", name]),
},
context: {
create: ({ name, description, docker }) =>
run(["context", "create", name, ...formatArgs({ description, docker })]),
update: ({ name, description, docker }) =>
run(["context", "update", name, ...formatArgs({ description, docker })]),
inspect: (name) => runInspect<Docker.Context>(["context", "inspect", name]),
remove: (name, force) => run(["context", "rm", ...(force ? ["-f"] : []), name]),
},
network: {
create: ({ name, driver, ipv6, label, context }) =>
run([
...formatArgs({ context }),
"network",
"create",
name,
...formatArgs({ driver, ipv6, label }),
]),
connect: ({ network, container, alias, context }) =>
run([
...formatArgs({ context }),
"network",
"connect",
network,
container,
...(alias ? alias.flatMap((a) => ["--alias", a]) : []),
]),
disconnect: ({ network, container, context }) =>
run([...formatArgs({ context }), "network", "disconnect", network, container]),
inspect: (name, context) =>
runInspect<Docker.Network>([...formatArgs({ context }), "network", "inspect", name]),
remove: (id, context) => run([...formatArgs({ context }), "network", "rm", id]),
},
swarm: {
init: ({ context, ...options }) =>
run([...formatArgs({ context }), "swarm", "init", ...formatArgs(options)]),
info: (context) =>
run([...formatArgs({ context }), "info", "--format", "{{json .Swarm}}"]).pipe(
Effect.map((result) => JSON.parse(result.stdout) as Docker.SwarmInfo),
),
leave: (force, context) =>
run([...formatArgs({ context }), "swarm", "leave", ...(force ? ["--force"] : [])]),
},
service: {
create: ({ context, image, command, args, ...options }) =>
run([
...formatArgs({ context }),
"service",
"create",
...formatArgs({ ...options }),
image,
...(command ?? []),
...(args ?? []),
]),
update: ({ context, id, ...options }) =>
run([
...formatArgs({ context }),
"service",
"update",
"--detach=false",
...formatArgs({ ...options }),
id,
]),
inspect: (id, context) =>
runInspect([...formatArgs({ context }), "service", "inspect", id]),
remove: (id, context) => run([...formatArgs({ context }), "service", "rm", id]),
},
});
});
/** The Docker CLI client, running `docker` (or `DOCKER_BIN`). */
export const DockerLive = dockerLive();
export const dockerContextName = (context: Docker.ContextRef | undefined): string | undefined => {
const value = typeof context === "string" ? context : context?.name;
const normalized = value?.trim();
return normalized && normalized.length > 0 ? normalized : undefined;
};
/**
* Resolve an {@link Docker.EngineRef} to a context name. A `Docker.Swarm`
* reference (narrowed by its `nodeId` attribute) contributes the context the
* swarm was initialized on.
*/
export const dockerEngineContextName = (ref: Docker.EngineRef | undefined): string | undefined => {
if (typeof ref === "object" && ref !== null && "nodeId" in ref) {
return dockerContextName((ref as { context?: string }).context);
}
return dockerContextName(ref as Docker.ContextRef | undefined);
};
export const dockerPhysicalName = (
id: string,
props: { name?: string } | undefined,
instanceId: string,
// Swarm service names are capped at 63 characters; other Docker object
// names accept much longer values.
maxLength = 128,
) =>
props?.name
? Effect.succeed(props.name)
: createPhysicalName({ id, instanceId, maxLength, lowercase: true });
/**
* A failing `docker` command splits its diagnosis over both streams: the
* builder writes the step log to one and the reason it stopped to the other,
* and which carries which depends on the builder, the progress mode and
* whether the output is a terminal. A build that fails inside a `RUN` step
* therefore reports nothing but its exit code when only `stderr` is kept.
* Keep both, the reason first, so the error says why the build failed.
*/
const failureOutput = (stderr: string, stdout: string) => {
const output = [stderr, stdout].filter((text) => text.length > 0);
return output.length > 0 ? output.join("\n") : "the command wrote no output.";
};
/** Constructs a PlatformError from a command execution result. */
const systemError = (input: {
_tag: SystemErrorTag;
args: Array<string>;
description?: string;
cause?: unknown;
}) =>
new PlatformError(
new SystemError({
_tag: input._tag,
module: "Docker",
method: input.args.slice(0, 2).join("."),
pathOrDescriptor: input.args.join(" "),
description: input.description,
cause: input.cause,
}),
);
/**
* `--secret id=<id>,env=<var>` per secret, with each value under a generated
* variable name: an id is the Dockerfile author's choice and may collide with
* the environment Docker itself reads (`PATH`, `DOCKER_HOST`).
*/
const buildSecrets = (secrets: Record<string, string | Redacted.Redacted<string>> | undefined) => {
const args: Array<string> = [];
const env: Record<string, string> = {};
Object.entries(secrets ?? {}).forEach(([id, value], index) => {
const variable = `ALCHEMY_BUILD_SECRET_${index}`;
args.push("--secret", `id=${id},env=${variable}`);
env[variable] = Redacted.isRedacted(value) ? Redacted.value(value) : value;
});
return { args, env };
};
/** Formats a set of options into a list of command-line arguments. */
const formatArgs = (
options: Record<
string,
boolean | string | number | undefined | Record<string, string> | Array<string>
>,
) => {
const args: Array<string> = [];
for (const [key, value] of Object.entries(options)) {
// `0` is meaningful (`--replicas 0`, `--update-parallelism 0`), so only
// absent, `false` and empty values are omitted.
if (value === undefined || value === false || value === "") continue;
const prefix = key.length > 1 ? `--${key}` : `-${key}`;
if (value === true) {
args.push(prefix);
} else if (typeof value === "string") {
args.push(prefix, value);
} else if (typeof value === "number") {
args.push(prefix, String(value));
} else if (Array.isArray(value)) {
for (const item of value) {
args.push(prefix, item);
}
} else if (value !== null && typeof value === "object") {
for (const [k, v] of Object.entries(value)) {
args.push(prefix, `${k}=${v}`);
}
}
}
return args;
};