@zuke/docker-compose

`@zuke/docker-compose` — typed Docker Compose task wrappers for Zuke builds.

@zuke/docker-compose on JSR ↗ 48 symbols

Symbols

ComposeProbe

type

type ComposeProbe = unknown

Probes whether a candidate Compose invocation is runnable on this host. Receives the binary-and-prefix argv (["docker", "compose"] or ["docker-compose"]) and resolves to true when it works. Injectable so detection can be unit-tested without a real Docker install.

defaultComposeProbe

function

async function defaultComposeProbe(argv: unknown): Promise<boolean>

The default ComposeProbe: run the candidate's version subcommand quietly and treat a zero exit as success. A missing binary resolves to false rather than throwing, so detection can fall through to the next candidate.

DockerComposeBuildSettings

class

class DockerComposeBuildSettings extends DockerComposeSettings

Settings for compose build.

Member	Signature	Doc
`noCache`	`noCache(): this`	Do not use the layer cache (`--no-cache`).
`pull`	`pull(): this`	Always attempt to pull newer base images (`--pull`).
`buildArg`	`buildArg(key: string, value: string): this`	Pass a build-time variable (`--build-arg KEY=value`); repeatable.
`services`	`services(...names: string[]): this`	Restrict to specific services (positional); optional.

dockerComposeCanary

function

function dockerComposeCanary(configure: Configure<DockerComposeCanarySettings>): DockerComposeCanary

A Compose project as a canary platform, for @zuke/canary:

c.platform(dockerComposeCanary((d) =>
  d.service("app").canaryService("app-canary").replicas(4)
    .image(this.image.value)
    .stableImageVariable("APP_IMAGE")
    .canaryImageVariable("APP_CANARY_IMAGE")
    .compose((s) => s.file("compose.yml").projectName("shop"))
))

The lambda runs on every call, so it may read resolved parameters; after stage, the services, replicas and variables are the ones it recorded, and every call refuses unless d.compose(...) gives the global flags stage recorded and Compose reports the two services in the project stage saw. Every move is up -d --no-deps --scale <service>=<n> <service> (with --wait when n is not 0), run with the image variables set:

- stage — ps --format {{.Image}} <stable> reads the stable image, images --quiet <stable> its ID and ps -a --format '{{.Label "com.docker.compose.project"}}' <stable> its one project, pull --policy missing <canary>, the rollout is recorded, then the stable service to every replica (--no-recreate) and the canary service to none. From here on, the stable variable is the recorded sha256:<id> on every command that may create a stable replica, and every move that sets an ID adds --pull never, since an ID cannot be pulled. - expose, promote, abort with a record — first ps -a --format '{{.Label "com.docker.compose.project"}}' <stable> <canary>, which must report exactly the recorded project. - expose — the canary service (--no-recreate) to its share and the stable service (--no-recreate) to the rest, the growing one first; ps checks the canary runs the candidate and images --quiet pins its ID on the first step, which later steps and promote then use. - promote — the canary service to every replica, the stable service recreated on the pinned candidate ID and checked with images --quiet, the canary service to none. Not durable until the candidate is written where the stable variable comes from. - abort — images --quiet reads the stable replicas' IDs (run by hand, ps the running ones' references and ps -a every one's; on a recorded rollout off the ID, ps then counts the running ones). All on the stable image: the stable service back to every replica (--no-recreate). None running: the stable service first, recreated onto the stable image, the canary untouched. Some running on another image: the canary service to every replica on the stable image, then the stable service recreated on it. The stable replicas are then read again and must be on the stable image, before the canary service goes to none. Run by hand, the stable image is the one set with .stable(...). A rollback with nothing recorded runs nothing: nothing was staged.

The stable service's scale: in the Compose file must equal .replicas(...), and Compose 2.21 or later (docker compose) is required.

DockerComposeCanary

class

class DockerComposeCanary

A Compose project as a canary platform. Create one with dockerComposeCanary; hand it to @zuke/canary's c.platform(...).

Exposure is the canary's share of the replicas, so it is quantised.

Member	Signature	Doc
`describe`	`describe(): string`	`"Compose service app"`, for the build summary.
`stage`	`stage(ctx: DockerComposeCanaryContext): Promise<void>`	Read the image the stable replicas run, make sure the candidate image is available (pulled unless it is already present), record the rollout — the two services, the replicas, the two variables, the two images and the stable replicas' image ID (`images --quiet`), which every later call acts on whatever the lambda says then, and the project — its global flags and the project Compose reports the stable replicas in, which every later call refuses to run without — and bring the project to exactly 0 %: the stable service at every replica, the canary service at none. The stable replicas are only added or removed, never recreated. Each call runs `d.compose(...)` once to resolve the global flags, and then once per command; a command it gives any other flags (a lambda that reads a clock, or changes what it closes over) is refused before it runs. A stage always starts afresh, so a re-run one records the flags it runs with. What the project check does not cover: the Docker daemon is not recorded, and the recorded image IDs are only a partial guard against another one. After `stage` every move passes `--pull never`, so one that creates a container fails on a daemon that lacks its image — the recorded stable ID, or the candidate — while one that only removes containers needs no image and goes ahead; and the reads compare IDs, so a rollback finds stable replicas on another image and a later step a canary on another candidate. A daemon or context (`DOCKER_HOST`, `DOCKER_CONTEXT`, a `.toolPath(...)`) that runs the same project name, with the same services on the same images, is not told apart. Nor is a change that keeps the project but changes the services' definitions: another `COMPOSE_FILE`, an env file that changes what they interpolate, or — with an explicit `-p` and no `-f` — a working directory or `.cwd(...)` that loads another `compose.yml` under the same project name. And the lambda's `.env(...)` and `.cwd(...)` are checked only through the project read at the start of each call; every later command re-checks only its flags, so the lambda must give the same `.env(...)` and `.cwd(...)` every time it runs.
`expose`	`expose(percent: number, ctx: DockerComposeCanaryContext): Promise<number>`	Run the canary service at `percent` of the replicas and the stable service at the rest, and return the share actually reached. Any share between 0 and 100 exclusive keeps at least one replica on each side, so a step never rounds to an untested 0 % or a premature 100 %. Whichever service grows is scaled first, so the total never dips below the replicas. Once the canary service has replicas, `ps` must show every one of them on the candidate — a canary whose `image:` does not read its variable is refused rather than analysed — and `images --quiet` must resolve them to one image ID. The first step records that ID, as the image the analysis judges; every later step and promote set the canary variable to it rather than the tag, and refuse a canary that resolves to another. The stable replicas are never recreated. The services and replicas are the ones `stage` recorded, and the call refuses before any command unless `d.compose(...)` still gives the global flags `stage` recorded, and before any other unless the project read (`ps -a` with the project label) reports the two services in the project `stage` saw.
`promote`	`promote(ctx: DockerComposeCanaryContext): Promise<void>`	Hand the stable service to the candidate: the canary service goes to every replica, the stable service is recreated with the stable variable set to the candidate's recorded image ID — the image the analysis judged, whatever the candidate tag names by now — `images --quiet` must then resolve every stable replica to that ID — or the call refuses, before it is recorded as promoted, since a stable `image:` that does not read the variable would have changed nothing — and the canary service goes back to none. The total never dips below the replicas; for a moment it is twice that. Idempotent. Like every call after `stage`, it refuses before any command unless `d.compose(...)` still gives the global flags `stage` recorded, and before any other unless the project read (`ps -a` with the project label) reports the two services in the project `stage` saw. This is not durable on its own. Compose has no state of its own to change: the variable is set for these commands only. Until the candidate is written where the stable variable comes from — the `.env` file, or the environment of whatever runs `docker compose up` next — a plain `docker compose up` puts the stable service back on the image that source still names, and at the replica count its `scale:` names, which is why that must equal `DockerComposeCanarySettings.replicas`. The build summary says so: `Persist: set APP_IMAGE=<candidate> (which must resolve to sha256:<id>) and keep scale: <replicas>`.
`abort`	`abort(ctx: DockerComposeCanaryContext): Promise<void>`	Put every replica back on the stable image, in the stable service, with the canary service at none. Idempotent. Which image, services and replicas depends on what this rollout recorded: - `stage` recorded them (a rollback mid-rollout, or after a promotion that failed part-way): the ones `stage` saw, whatever the lambda says now — in the project `stage` saw, too: unless `d.compose(...)` still gives the global flags `stage` recorded, this refuses before any command, and unless the project read (`ps -a` with the project label) then reports the two services in the project `stage` saw, before any other. Since the engine then leaves the run cancelled, the refusal names the recovery: the configuration and environment set back, and `rollout.abort` run by hand with `d.stable('sha256:<the recorded stable image ID>')`. - `stage` failed before recording them: nothing had changed, so nothing runs — and the settings are not even read. - Nothing recorded, on a rollback (`ctx.reason` is `"rollback"`): nothing was staged, so nothing runs — no container is read or scaled, and the settings are not even read. - Nothing recorded, run by hand (`rollout.abort` on its own, a fresh run, or an engine that names no reason): the settings, with the image set by `DockerComposeCanarySettings.stable`. Without one this refuses, since claiming a rollback it cannot do would be worse. Every command sets the stable variable to the image ID `stage` recorded, not to the reference, so a tag moved since cannot bring in an image nobody analysed; run by hand, there is only the reference. First it reads what the stable replicas run, and takes one of three courses: - All on the stable image — on a recorded rollout, `images --quiet` resolves them, stopped ones included, to exactly the recorded ID (a tag `ps` shows means whatever the tag names now, so it is not evidence); run by hand, `ps` shows at least one running and `ps -a` every container, stopped and created ones included, on the `.stable(...)` reference — a scale that keeps them starts the stopped ones, so one on another image would serve as stable. Mid-rollout they are. The stable service is only scaled back to every replica (`--no-recreate`). - None running — on a recorded rollout, `images --quiet` finds no stable replica at all (after a step to 100 %), or `ps` finds none running; run by hand, `ps` finds none running (a crashed or removed stable service, or a stopped project). The stable service comes up first, recreated onto the stable image where it must be, while the canary keeps serving untouched: recreating the canary first would take every serving container down at once. - Some running on another image — after a promotion, run by hand or part-way. Compose recreates them all at once, so the rollback mirrors a promotion: the canary service first goes to every replica on the stable image, then the stable service is recreated on it. Serving never drops to zero while anything serves: each service is recreated only while the other one serves. It can dip, though, on the surge course: Compose stops every container it recreates at once, so while the canary is recreated onto the stable image only the stable replicas serve, and while they are recreated only the canary does — fewer than `.replicas(...)` when the one left serving was only partly scaled. Whichever the course, the stable replicas are then read again — by ID on a recorded rollout, by reference run by hand — and a stable `image:` that does not read its variable is refused, leaving the canary serving, rather than reported as rolled back; only then does the canary service go to none. Like a promotion, the image is an override for these commands, so it lasts until a plain `docker compose up` reads the variable from wherever the project keeps it. A hand-run rollback — the one that undoes a promotion someone persisted — says so in the build summary, as promote does: `Persist: set APP_IMAGE=<stable> and keep scale: <replicas>`.
`exposure`	`exposure: replicas`	Compose runs replicas, so exposure is a share of instances.

DockerComposeCanaryContext

interface

interface DockerComposeCanaryContext

The part of the canary engine's context the Compose platform uses: the rollout's durable state, where the images are recorded, and the build summary. The engine hands a richer context; this is the narrow view.

Member	Signature	Doc
`reportSummary`	`reportSummary(pairs: SummaryPairs): void`	Add key/value pairs to the calling target's row in the build summary.
`state`	`state: TargetStateHandle`	The rollout's durable platform state, shared by every call.
`reason?`	`reason?: rollback \| hand-run`	Why `abort` runs: `"rollback"` when the engine undoes a rollout, `"hand-run"` for `rollout.abort` run on its own. An engine older than this field leaves it out, which is treated as a hand run — the behaviour from before the field existed.

DockerComposeCanarySettings

class

class DockerComposeCanarySettings

How dockerComposeCanary reaches the project, configured through its lambda.

Member	Signature	Doc
`service`	`service(name: string): this`	The service that serves the stable release, e.g. `app`. It must already be running: `stage` reads the image its replicas run, which is what a rollback returns them to.
`canaryService`	`canaryService(name: string): this`	The service that runs the candidate, e.g. `app-canary` — a second service in the same project, behind the same proxy, whose `image:` is `${<canaryImageVariable>}`. Give it `scale: 0` in the Compose file so a plain `docker compose up` does not start it.
`replicas`	`replicas(total: number): this`	How many replicas the stable and canary services share between them. A step sets the canary to its share of this and the stable service to the rest; `stage` and a rollback set the stable service to all of it. From 2 to 10000. Give the stable service the same `scale:` in the Compose file: a plain `docker compose up` sets every service back to its `scale:`.
`image`	`image(reference: string): this`	The candidate's image reference, which `stage` puts on the canary service.
`stableImageVariable`	`stableImageVariable(name: string): this`	The environment variable the stable service's `image:` is — the whole reference, as in `image: ${APP_IMAGE}`, not just a tag. Every command the platform runs sets it, so the project's `.env` need not: to the image the stable replicas ran when `stage` looked, to the candidate on promotion. Not a name Docker, Compose or the process reads as a setting — `DOCKER_`, `COMPOSE_`, `BUILDKIT_`, `BUILDX_`, `XDG_`, `LD_`, `DYLD_`, `_PROXY`, `PATH`, `PATHEXT`, `HOME`, `USERPROFILE`, `SystemRoot`, `TMPDIR`, `TEMP`, `TMP`, `SSH_AUTH_SOCK`, `SSL_CERT_FILE` or `SSL_CERT_DIR`, in any case — and not the canary's variable in another case.
`canaryImageVariable`	`canaryImageVariable(name: string): this`	The environment variable the canary service's `image:` is, as in `image: ${APP_CANARY_IMAGE:-${APP_IMAGE}}`. Every command that brings up the canary sets it to the candidate.
`stable`	`stable(image: string): this`	The image to put the stable service back on when `rollout.abort` is run by hand — a reference with no whitespace or control characters. Such a run is fresh, with no record of a rollout, so it has nothing else to go on — and the release it is undoing has usually been promoted already. A rollback the engine runs does not use it: mid-rollout it returns to the image ID `stage` saw the stable replicas running, and with nothing recorded it runs nothing, since nothing was staged.
`compose`	`compose(configure: Configure<DockerComposeSettings>): this`	Global flags for every Compose command the platform runs — `(s) => s.file("compose.yml").projectName("shop")`, or `.usePlugin()` to skip detection. Compose 2.21 or later (`docker compose`) is required: the project check's `{{.Label ...}}` template is not in earlier releases, and the v1 `docker-compose` binary has no `--wait`, `pull --policy` or `ps --format`. Trailing `.args(...)` are refused, since they would land after the service each command names — a guard against an accident, not a security boundary: this lambda is the build's own code and can run Compose however it likes. A non-zero exit fails the call even with `.noThrow()`. The flags it gives select the project, so `stage` records them (as argv: what `.env(...)` passes is never recorded) and every later call refuses unless they are the same, in the same order. It also records the project Compose reports the stable replicas in, and every later call refuses unless Compose still reports the services there — which covers whatever else resolves the project: `COMPOSE_PROJECT_NAME` in the environment, a `.env` or `--env-file`, `.env(...)` and `.cwd(...)` here, the working directory. Not covered: a Docker context, `DOCKER_HOST` or `.toolPath(...)` that reaches another daemon running the same project with the same services on the same images; a `COMPOSE_FILE` or env file that keeps the project but changes the services' definitions, or — with an explicit `-p` and no `-f` — a working directory or `.cwd(...)` that loads another `compose.yml` under the same name. And `.env(...)` and `.cwd(...)` are checked only at each call's project read, while later commands re-check only the flags, so this lambda must give the same ones every time it runs.
`runner`	`runner(run: DockerComposeSettingsRunner): this`	Replace how each prepared command is run. The default runs it; this is for a test, or for a build that executes Compose through something else.
`service_?`	`service_?: string`	The service that serves the stable release (set by `service`).
`canaryService_?`	`canaryService_?: string`	The service that runs the candidate (set by `canaryService`).
`replicas_?`	`replicas_?: number`	The replicas the two services share (set by `replicas`).
`image_?`	`image_?: string`	The candidate's image (set by `image`).
`stableImageVariable_?`	`stableImageVariable_?: string`	The variable the stable service's image reads (set by `stableImageVariable`).
`canaryImageVariable_?`	`canaryImageVariable_?: string`	The variable the canary service's image reads (set by `canaryImageVariable`).
`stable_?`	`stable_?: string`	The image a hand-run rollback returns to (set by `stable`).
`compose_?`	`compose_?: Configure<DockerComposeSettings>`	Global Compose flags for every command (set by `compose`).
`runner_`	`runner_: DockerComposeSettingsRunner`	How each command is run (set by `runner`).

DockerComposeCommitSettings

class

class DockerComposeCommitSettings extends DockerComposeSettings

Settings for compose commit.

Member	Signature	Doc
`service`	`service(name: string): this`	The service whose container to commit (required).
`reference`	`reference(value: string): this`	The image reference to create, e.g. `my-app:test`.
`author`	`author(value: string): this`	Image author (`--author`).
`message`	`message(value: string): this`	Commit message (`--message`).
`change`	`change(...instructions: string[]): this`	Apply a Dockerfile instruction to the created image (`--change`).
`index`	`index(value: number): this`	Pick the replica to commit when the service has several (`--index`).
`noPause`	`noPause(): this`	Leave the container running during the commit (`--pause=false`). Compose pauses it by default so the filesystem cannot change mid-capture; turning that off trades a consistent image for uninterrupted service.

DockerComposeConfigSettings

class

class DockerComposeConfigSettings extends DockerComposeSettings

Settings for compose config.

Member	Signature	Doc
`quietOutput`	`quietOutput(): this`	Only validate, printing nothing (`-q`).
`servicesOnly`	`servicesOnly(): this`	Print the service names only (`--services`).
`volumesOnly`	`volumesOnly(): this`	Print the volume names only (`--volumes`).
`format`	`format(value: string): this`	Output format (`--format`), e.g. `yaml` or `json`.

DockerComposeCpSettings

class

class DockerComposeCpSettings extends DockerComposeSettings

Settings for compose cp.

Compose copies between a service container and the local filesystem, so exactly one side names a service. Naming both or neither is refused rather than handed to Compose as a path it cannot resolve.

Member	Signature	Doc
`fromService`	`fromService(service: string, path: PathLike): this`	Copy out of `service` at `path` (`SERVICE:PATH`).
`fromLocal`	`fromLocal(path: PathLike): this`	Copy out of a local path.
`toService`	`toService(service: string, path: PathLike): this`	Copy into `service` at `path` (`SERVICE:PATH`).
`toLocal`	`toLocal(path: PathLike): this`	Copy into a local path.
`index`	`index(value: number): this`	Pick the replica to copy from when the service has several (`--index`).
`all`	`all(): this`	Include containers created by `compose run` (`--all`).
`archive`	`archive(): this`	Preserve uid/gid information (`--archive`).
`followLink`	`followLink(): this`	Follow symbolic links in the source path (`--follow-link`).

DockerComposeCreateSettings

class

class DockerComposeCreateSettings extends DockerComposeSettings

Settings for compose create.

Member	Signature	Doc
`services`	`services(...names: string[]): this`	Restrict creation to these services.
`build`	`build(): this`	Build images before creating containers (`--build`).
`noBuild`	`noBuild(): this`	Never build, whatever the policy says (`--no-build`).
`forceRecreate`	`forceRecreate(): this`	Recreate containers even when their configuration has not changed (`--force-recreate`).
`noRecreate`	`noRecreate(): this`	Leave existing containers in place (`--no-recreate`).
`removeOrphans`	`removeOrphans(): this`	Remove containers for services no longer in the file (`--remove-orphans`).
`quietPull`	`quietPull(): this`	Pull without progress output (`--quiet-pull`).
`pull`	`pull(policy: DockerComposePullPolicy): this`	When to pull images before creating (`--pull`).
`scale`	`scale(service: string, replicas: number): this`	Create `replicas` containers for `service` (`--scale`).
`yes`	`yes(): this`	Answer every prompt affirmatively (`--yes`), so an unattended run cannot stall.

DockerComposeDownSettings

class

class DockerComposeDownSettings extends DockerComposeSettings

Settings for compose down.

Member	Signature	Doc
`volumes`	`volumes(): this`	Also remove named and anonymous volumes (`-v`).
`removeOrphans`	`removeOrphans(): this`	Remove containers for services no longer defined (`--remove-orphans`).
`rmi`	`rmi(type: string): this`	Remove images of the given type (`--rmi`), e.g. `all` or `local`.
`timeout`	`timeout(seconds: number): this`	Shutdown timeout in seconds (`-t`).

DockerComposeEventsSettings

class

class DockerComposeEventsSettings extends DockerComposeSettings

Settings for compose events.

Member	Signature	Doc
`services`	`services(...names: string[]): this`	Restrict the stream to these services.
`json`	`json(): this`	Emit each event as a JSON object (`--json`).
`since`	`since(timestamp: string): this`	Include events since a timestamp (`--since`).
`until`	`until(timestamp: string): this`	Stop streaming at a timestamp (`--until`). Without it the command streams until interrupted, so a build target that awaits it blocks — bound the run with this or with `.killAfter(ms)`.

DockerComposeExecSettings

class

class DockerComposeExecSettings extends DockerComposeSettings

Settings for compose exec.

Member	Signature	Doc
`service`	`service(name: string): this`	The service whose container to exec into (required).
`detach`	`detach(): this`	Run in the background (`-d`).
`noTty`	`noTty(): this`	Disable pseudo-TTY allocation (`-T`).
`workdir`	`workdir(path: PathLike): this`	Working directory inside the container (`-w`).
`envVar`	`envVar(key: string, value: string): this`	Set an environment variable (`-e KEY=value`); repeatable.
`commandArgs`	`commandArgs(...args: Array<string \| number>): this`	The command and arguments to execute.

DockerComposeExportSettings

class

class DockerComposeExportSettings extends DockerComposeSettings

Settings for compose export.

Member	Signature	Doc
`service`	`service(name: string): this`	The service whose container filesystem to export (required).
`output`	`output(path: PathLike): this`	Write the tar archive to a file (`--output`) instead of stdout. Prefer it: a tar stream captured as the command's stdout goes through Zuke's output buffer, which is text-shaped and size-capped.
`index`	`index(value: number): this`	Pick the replica to export when the service has several (`--index`).

DockerComposeImagesSettings

class

class DockerComposeImagesSettings extends DockerComposeListingSettings

Settings for compose images.

Member	Signature	Doc
`services`	`services(...names: string[]): this`	Restrict the listing to these services.

DockerComposeKillSettings

class

class DockerComposeKillSettings extends DockerComposeSettings

Settings for compose kill.

Member	Signature	Doc
`services`	`services(...names: string[]): this`	Restrict the kill to these services.
`signal`	`signal(name: string): this`	The signal to send (`--signal`), `SIGKILL` by default. Send `SIGTERM` to let a service run its shutdown path — `kill` skips the grace period `stop` gives it.
`removeOrphans`	`removeOrphans(): this`	Remove containers for services no longer in the file (`--remove-orphans`).

DockerComposeListingSettings

class

class DockerComposeListingSettings extends DockerComposeSettings

Shared by the listing subcommands that accept --format and --quiet.

--format json is what makes these readable by a build rather than by a person, so the convenience json spells it rather than leaving the caller to remember the value.

Member	Signature	Doc
`format`	`format(value: string): this`	Format the output (`--format`), e.g. `table` or `json`.
`json`	`json(): this`	Emit JSON (`--format json`).
`quietOutput`	`quietOutput(): this`	Print only identifiers or names (`--quiet`).

DockerComposeLogsSettings

class

class DockerComposeLogsSettings extends DockerComposeSettings

Settings for compose logs.

Member	Signature	Doc
`follow`	`follow(): this`	Stream new log output (`-f`).
`timestamps`	`timestamps(): this`	Prefix each line with a timestamp (`-t`).
`tail`	`tail(lines: number \| all): this`	Show only the last N lines, or `all` (`--tail`).
`services`	`services(...names: string[]): this`	Restrict to specific services (positional); optional.

DockerComposeLsSettings

class

class DockerComposeLsSettings extends DockerComposeListingSettings

Settings for compose ls, which lists Compose projects rather than services.

Member	Signature	Doc
`all`	`all(): this`	Include stopped projects (`--all`).
`filter`	`filter(expression: string): this`	Filter the listing (`--filter`), e.g. `name=my-project`.

DockerComposePauseSettings

class

class DockerComposePauseSettings extends DockerComposeServiceListSettings

Settings for compose pause.

DockerComposePortSettings

class

class DockerComposePortSettings extends DockerComposeSettings

Settings for compose port, which prints the host address a service's container port was published on.

Member	Signature	Doc
`service`	`service(name: string): this`	The service to ask about (required).
`privatePort`	`privatePort(port: number): this`	The container-side port to look up (required).
`protocol`	`protocol(value: tcp \| udp): this`	The protocol of the binding (`--protocol`), `tcp` by default.
`index`	`index(value: number): this`	Pick the replica to ask when the service has several (`--index`).

DockerComposePsSettings

class

class DockerComposePsSettings extends DockerComposeSettings

Settings for compose ps.

Member	Signature	Doc
`all`	`all(): this`	Show stopped containers too (`-a`).
`quietOutput`	`quietOutput(): this`	Only show container IDs (`-q`).
`servicesOnly`	`servicesOnly(): this`	Display services instead of containers (`--services`).
`format`	`format(value: string): this`	Output format (`--format`): `table`, `json`, or a Go template such as `{{.Image}}`, which prints one line per container.
`services`	`services(...names: string[]): this`	Restrict to specific services (positional); optional.

DockerComposePullPolicy

type

type DockerComposePullPolicy = always | missing | never

When compose up fetches images before starting: always on every start, missing only when the image is absent locally, never at all.

DockerComposePullSettings

class

class DockerComposePullSettings extends DockerComposeSettings

Settings for compose pull.

Member	Signature	Doc
`ignorePullFailures`	`ignorePullFailures(): this`	Continue past services whose pull fails (`--ignore-pull-failures`).
`policy`	`policy(value: Exclude<DockerComposePullPolicy, never>): this`	Which images to pull (`--policy`): `missing` skips an image already present locally — so a locally built image is not looked up in a registry — and `always` fetches every one.
`quietOutput`	`quietOutput(): this`	Pull without printing progress (`-q`).
`services`	`services(...names: string[]): this`	Restrict to specific services (positional); optional.

DockerComposePushSettings

class

class DockerComposePushSettings extends DockerComposeSettings

Settings for compose push.

Member	Signature	Doc
`ignorePushFailures`	`ignorePushFailures(): this`	Continue past services whose push fails (`--ignore-push-failures`).
`services`	`services(...names: string[]): this`	Restrict to specific services (positional); optional.

DockerComposeRestartSettings

class

class DockerComposeRestartSettings extends DockerComposeSettings

Settings for compose restart.

Member	Signature	Doc
`timeout`	`timeout(seconds: number): this`	Restart timeout in seconds (`-t`).
`services`	`services(...names: string[]): this`	Restrict to specific services (positional); optional.

DockerComposeRmSettings

class

class DockerComposeRmSettings extends DockerComposeSettings

Settings for compose rm.

Member	Signature	Doc
`force`	`force(): this`	Do not prompt for confirmation (`-f`).
`stop`	`stop(): this`	Stop the containers first if needed (`-s`).
`volumes`	`volumes(): this`	Also remove anonymous volumes (`-v`).
`services`	`services(...names: string[]): this`	Restrict to specific services (positional); optional.

DockerComposeRunSettings

class

class DockerComposeRunSettings extends DockerComposeSettings

Settings for compose run.

Member	Signature	Doc
`service`	`service(name: string): this`	The service to run (required).
`rm`	`rm(): this`	Remove the container after it exits (`--rm`).
`detach`	`detach(): this`	Run in the background (`-d`).
`noDeps`	`noDeps(): this`	Do not start linked services (`--no-deps`).
`name`	`name(value: string): this`	Assign a container name (`--name`).
`envVar`	`envVar(key: string, value: string): this`	Set an environment variable (`-e KEY=value`); repeatable.
`commandArgs`	`commandArgs(...args: Array<string \| number>): this`	The command and arguments to run inside the container.

DockerComposeScaleSettings

class

class DockerComposeScaleSettings extends DockerComposeSettings

Settings for compose scale.

Member	Signature	Doc
`scale`	`scale(service: string, replicas: number): this`	Scale `service` to `replicas` instances; repeatable (required).
`noDeps`	`noDeps(): this`	Do not start linked services (`--no-deps`).

DockerComposeServiceListSettings

class

class DockerComposeServiceListSettings extends DockerComposeSettings

Settings shared by compose pause and compose unpause, which take only a service list.

Member	Signature	Doc
`services`	`services(...names: string[]): this`	Restrict the command to these services.

DockerComposeSettings

class

class DockerComposeSettings extends ToolSettings

Base for all Compose subcommand settings. Holds the invocation prefix (docker compose vs docker-compose) and the global options that precede every subcommand (-f, -p, --profile, …), and resolves the prefix at run time unless it was pinned with usePlugin/useStandalone.

Member	Signature	Doc
`file`	`file(path: PathLike): this`	Add a Compose file (`-f`); repeatable, order-significant.
`projectName`	`projectName(name: string): this`	Set the project name (`-p`).
`profile`	`profile(name: string): this`	Enable a service profile (`--profile`); repeatable.
`projectDirectory`	`projectDirectory(path: PathLike): this`	Set the project working directory (`--project-directory`).
`envFile`	`envFile(path: PathLike): this`	Load environment from a file (`--env-file`).
`usePlugin`	`usePlugin(): this`	Force the v2 plugin form (`docker compose`) and skip detection.
`useStandalone`	`useStandalone(): this`	Force the v1 standalone form (`docker-compose`) and skip detection.
`run`	`run(): Promise<CommandOutput>`	Resolve the invocation prefix (unless pinned) and run, so the same build works against either the v2 plugin or the v1 standalone binary.

DockerComposeSettingsRunner

type

type DockerComposeSettingsRunner = unknown

Runs one prepared Compose command and returns its output. env holds the image variables the platform already applied to settings — handed over as well so a runner that executes Compose some other way, or a test, sees them. The default runs the settings; inject another with DockerComposeCanarySettings.runner. An output with a non-zero exit code fails the call, as a rejection does.

DockerComposeStartSettings

class

class DockerComposeStartSettings extends DockerComposeSettings

Settings for compose start.

Member	Signature	Doc
`services`	`services(...names: string[]): this`	Restrict to specific services (positional); optional.

DockerComposeStopSettings

class

class DockerComposeStopSettings extends DockerComposeSettings

Settings for compose stop.

Member	Signature	Doc
`timeout`	`timeout(seconds: number): this`	Shutdown timeout in seconds (`-t`).
`services`	`services(...names: string[]): this`	Restrict to specific services (positional); optional.

DockerComposeTasks

const

const DockerComposeTasks: DockerComposeTasksApi

Typed task functions for Docker Compose (docker compose/docker-compose).

DockerComposeTasksApi

interface

interface DockerComposeTasksApi

The shape of DockerComposeTasks.

Member	Signature	Doc
`up`	`up(configure?: Configure<DockerComposeUpSettings>): Promise<CommandOutput>`	Create and start services: `compose up`.
`down`	`down(configure?: Configure<DockerComposeDownSettings>): Promise<CommandOutput>`	Stop and remove services: `compose down`.
`build`	`build(configure?: Configure<DockerComposeBuildSettings>): Promise<CommandOutput>`	Build service images: `compose build`.
`pull`	`pull(configure?: Configure<DockerComposePullSettings>): Promise<CommandOutput>`	Pull service images: `compose pull`.
`push`	`push(configure?: Configure<DockerComposePushSettings>): Promise<CommandOutput>`	Push service images: `compose push`.
`run`	`run(configure?: Configure<DockerComposeRunSettings>): Promise<CommandOutput>`	Run a one-off command: `compose run`.
`exec`	`exec(configure?: Configure<DockerComposeExecSettings>): Promise<CommandOutput>`	Exec into a running service: `compose exec`.
`logs`	`logs(configure?: Configure<DockerComposeLogsSettings>): Promise<CommandOutput>`	View service logs: `compose logs`.
`ps`	`ps(configure?: Configure<DockerComposePsSettings>): Promise<CommandOutput>`	List containers: `compose ps`.
`config`	`config(configure?: Configure<DockerComposeConfigSettings>): Promise<CommandOutput>`	Render the resolved configuration: `compose config`.
`start`	`start(configure?: Configure<DockerComposeStartSettings>): Promise<CommandOutput>`	Start existing services: `compose start`.
`stop`	`stop(configure?: Configure<DockerComposeStopSettings>): Promise<CommandOutput>`	Stop running services: `compose stop`.
`restart`	`restart(configure?: Configure<DockerComposeRestartSettings>): Promise<CommandOutput>`	Restart services: `compose restart`.
`rm`	`rm(configure?: Configure<DockerComposeRmSettings>): Promise<CommandOutput>`	Remove stopped service containers: `compose rm`.
`create`	`create(configure?: Configure<DockerComposeCreateSettings>): Promise<CommandOutput>`	Create containers without starting them: `compose create`.
`kill`	`kill(configure?: Configure<DockerComposeKillSettings>): Promise<CommandOutput>`	Force-stop service containers: `compose kill`.
`pause`	`pause(configure?: Configure<DockerComposePauseSettings>): Promise<CommandOutput>`	Pause services: `compose pause`.
`unpause`	`unpause(configure?: Configure<DockerComposeUnpauseSettings>): Promise<CommandOutput>`	Resume paused services: `compose unpause`.
`scale`	`scale(configure?: Configure<DockerComposeScaleSettings>): Promise<CommandOutput>`	Set service replica counts: `compose scale`.
`wait`	`wait(configure?: Configure<DockerComposeWaitSettings>): Promise<CommandOutput>`	Block until services stop: `compose wait`. Keeps the ordinary contract — a non-zero container status fails the target. Use `DockerComposeTasksApi.waitExitCode` when the status is the answer rather than a failure.
`cp`	`cp(configure?: Configure<DockerComposeCpSettings>): Promise<CommandOutput>`	Copy between a service container and the local filesystem: `compose cp`.
`top`	`top(configure?: Configure<DockerComposeTopSettings>): Promise<CommandOutput>`	Show running processes: `compose top`.
`export`	`export(configure?: Configure<DockerComposeExportSettings>): Promise<CommandOutput>`	Export a container filesystem as a tar archive: `compose export`.
`commit`	`commit(configure?: Configure<DockerComposeCommitSettings>): Promise<CommandOutput>`	Create an image from a container: `compose commit`.
`images`	`images(configure?: Configure<DockerComposeImagesSettings>): Promise<CommandOutput>`	List the images the containers use: `compose images`.
`volumes`	`volumes(configure?: Configure<DockerComposeVolumesSettings>): Promise<CommandOutput>`	List the project's volumes: `compose volumes`.
`ls`	`ls(configure?: Configure<DockerComposeLsSettings>): Promise<CommandOutput>`	List Compose projects: `compose ls`.
`version`	`version(configure?: Configure<DockerComposeVersionSettings>): Promise<CommandOutput>`	Report the Compose version: `compose version`.
`port`	`port(configure?: Configure<DockerComposePortSettings>): Promise<CommandOutput>`	Print a published port binding: `compose port`.
`events`	`events(configure?: Configure<DockerComposeEventsSettings>): Promise<CommandOutput>`	Stream container events: `compose events`.
`waitExitCode`	`waitExitCode(configure?: Configure<DockerComposeWaitSettings>): Promise<number>`	The exit status the waited-on container stopped with. `compose wait` exits with the container's own status, so every code is a legitimate answer and none is left to mean "compose broke". This hands the code back rather than failing the target, and still fails when compose never reached a container at all.
`servicePort`	`servicePort(configure?: Configure<DockerComposePortSettings>): Promise<number>`	The host port a service's container port was published on. The point of letting Compose pick an ephemeral port is asking which one it picked, which is what this returns.
`composeVersion`	`composeVersion(configure?: Configure<DockerComposeVersionSettings>): Promise<DockerComposeVersion>`	The installed Compose version, parsed from `compose version --format json`.

DockerComposeTopSettings

class

class DockerComposeTopSettings extends DockerComposeSettings

Settings for compose top.

Member	Signature	Doc
`services`	`services(...names: string[]): this`	Restrict the report to these services.

DockerComposeUnpauseSettings

class

class DockerComposeUnpauseSettings extends DockerComposeServiceListSettings

Settings for compose unpause.

DockerComposeUpSettings

class

class DockerComposeUpSettings extends DockerComposeSettings

Settings for compose up.

Member	Signature	Doc
`detach`	`detach(): this`	Run in the background (`-d`).
`build`	`build(): this`	Build images before starting (`--build`).
`forceRecreate`	`forceRecreate(): this`	Recreate containers even if unchanged (`--force-recreate`).
`noRecreate`	`noRecreate(): this`	Leave containers that already exist as they are, even when their configuration changed (`--no-recreate`). Scaling a service with it only adds or removes replicas; the ones already running keep their image.
`removeOrphans`	`removeOrphans(): this`	Remove containers for services no longer defined (`--remove-orphans`).
`wait`	`wait(): this`	Wait until services are running/healthy (`--wait`).
`abortOnContainerExit`	`abortOnContainerExit(): this`	Stop all containers if any container stops (`--abort-on-container-exit`).
`noDeps`	`noDeps(): this`	Start only the named services, leaving their dependencies alone (`--no-deps`). Without it compose starts or recreates a dependency that is stopped or whose configuration changed. With an already-healthy stack the two agree, so the difference shows up only on the runs where a dependency was not ready — which is where a target that meant "just this service" wants to be explicit.
`pull`	`pull(policy: DockerComposePullPolicy): this`	When to fetch images before starting (`--pull`). `always` keeps a stack on the current published images rather than whatever was pulled last; `missing` fetches only what is absent locally; `never` uses what is there. Distinct from `DockerComposeBuildSettings.pull`, which is `build --pull`, and from the `pull` task, which is the subcommand — each mirrors its own command.
`exitCodeFrom`	`exitCodeFrom(service: string): this`	Exit with this service's container's exit code (`--exit-code-from`).
`scale`	`scale(service: string, instances: number): this`	Scale a service to N instances (`--scale service=N`); repeatable.
`services`	`services(...names: string[]): this`	Restrict to specific services (positional); optional.

DockerComposeVersion

interface

interface DockerComposeVersion

The version report compose version --format json emits.

Member	Signature	Doc
`version`	`version: string`	The Compose version string, e.g. `v5.1.1`.

DockerComposeVersionSettings

class

class DockerComposeVersionSettings extends DockerComposeSettings

Settings for compose version.

Member	Signature	Doc
`format`	`format(value: string): this`	Format the output (`--format`), `pretty` or `json`.
`json`	`json(): this`	Emit JSON (`--format json`).
`short`	`short(): this`	Print only the version number (`--short`).

DockerComposeVolumesSettings

class

class DockerComposeVolumesSettings extends DockerComposeListingSettings

Settings for compose volumes.

Member	Signature	Doc
`services`	`services(...names: string[]): this`	Restrict the listing to the volumes these services use.

DockerComposeWaitSettings

class

class DockerComposeWaitSettings extends DockerComposeSettings

Settings for compose wait.

The command blocks until the named services' containers stop, then exits with the first container's own exit status. That makes its exit code a result rather than a failure — see DockerComposeTasks.waitExitCode, which hands the code back instead of failing the target.

Member	Signature	Doc
`services`	`services(...names: string[]): this`	The services to wait on (required).
`downProject`	`downProject(): this`	Tear the project down once the first container stops (`--down-project`), so a test run cleans up after itself without a second command.

ReplicaIndex

class

class ReplicaIndex

The --index flag that picks one replica of a scaled service.

cp, export, commit and port all take it with the same meaning and the same rendering, so they hold one of these rather than four copies of the field and the argv.push that goes with it. Each still exposes its own setter, because the public surface is per-command.

Member	Signature	Doc
`set`	`set(value: number): void`	Record the replica to act on.
`render`	`render(): string[]`	The flag, if one was set.

resetComposeInvocationCache_

function

function resetComposeInvocationCache_(): void

Clear the cached Compose invocation so the next resolveComposeInvocation re-detects. Internal test seam — the trailing underscore signals it is not part of the stable public API.

resolveComposeInvocation

function

function resolveComposeInvocation(probe?: ComposeProbe): Promise<string[]>

Resolve how Docker Compose is invoked on this host: ["docker", "compose"] for the v2 plugin or ["docker-compose"] for the v1 standalone binary. The v2 plugin is preferred; if neither is runnable a ToolNotFoundError is raised. The result is cached after the first successful detection (a failed detection is not cached, so a later call retries). Pass a custom ComposeProbe to override how candidates are tested.

ServiceList

class

class ServiceList

The trailing service-name operands most Compose subcommands accept.

Same reasoning as ReplicaIndex: the list and the way it is appended are identical wherever it appears, so it lives here once. Each settings class still exposes its own services() setter, because which subcommands take the operand — and what it means for each — is part of the public surface.

Member	Signature	Doc
`add`	`add(names: unknown): void`	Add service names to the list.
`isEmpty`	`isEmpty(): boolean`	Whether any service was named.
`render`	`render(): string[]`	The names, in the order they were added.