@lakutata/docker 3.0.0-beta.0

package/dist/cjs/docker/options/container/ContainerRemoveOptions.js

@@ -0,0 +1,34 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContainerRemoveOptions = void 0;
+const core_1 = require("@lakutata/core");
+const dto_1 = require("@lakutata/core/decorator/dto");
+/**
+ * How `DockerContainer.remove()` removes a container (`docker rm -v`): its anonymous volumes are removed with it, the
+ * named volumes are kept.
+ * @example
+ * ```typescript
+ * import {Docker} from 'lakutata/com/docker'
+ *
+ * declare const docker: Docker
+ *
+ * const container = await docker.getContainer('web')
+ * await container.remove({force: true})
+ * ```
+ */
+class ContainerRemoveOptions extends core_1.DTO {
+}
+exports.ContainerRemoveOptions = ContainerRemoveOptions;
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.Boolean().optional().default(false)),
+    __metadata("design:type", Boolean)
+], ContainerRemoveOptions.prototype, "force", void 0);

package/dist/cjs/docker/options/container/ContainerSettingOptions.d.ts

@@ -0,0 +1,137 @@
+import { DTO } from '@lakutata/core';
+import { ContainerDevice } from '../../types/ContainerDevice.js';
+import { type ContainerRestartPolicy } from '../../types/ContainerRestartPolicy.js';
+import { ContainerPort } from '../../types/ContainerPort.js';
+import { ContainerBind } from '../../types/ContainerBind.js';
+import { ContainerNetwork } from '../../types/ContainerNetwork.js';
+import { ContainerCapability } from '../../types/ContainerCapability.js';
+/**
+ * The settings of a container: given to {@link Docker.createContainer} and `DockerImage.run()` (create, then start),
+ * which use the image's defaults (command, environment…) for the settings absent, and to `DockerContainer.update()`,
+ * which changes the settings given and keeps the others: the limits and the restart policy live, the others by
+ * recreating the container. Every option is optional.
+ * @example
+ * ```typescript
+ * import {Docker, ContainerCapability} from 'lakutata/com/docker'
+ *
+ * declare const docker: Docker
+ *
+ * const image = await docker.pullImage({repo: 'nginx', tag: '1.27'})
+ * const container = await image.run({
+ *     name: 'web',
+ *     env: {TZ: 'UTC'},
+ *     memoryLimit: 256 * 1024 * 1024,
+ *     restartPolicy: 'unless-stopped',
+ *     ports: [{port: 80, type: 'tcp', hostPorts: [8080]}],
+ *     binds: [{hostPath: '/srv/web/html', containerPath: '/usr/share/nginx/html', rw: false}],
+ *     networks: [{networkName: 'front'}],
+ *     capabilities: [ContainerCapability.NET_ADMIN]
+ * })
+ * //The same container, with 512 MiB of memory, restarted 3 times at most when it fails
+ * await container.update({memoryLimit: 512 * 1024 * 1024, restartPolicy: 'on-failure:3'})
+ * ```
+ */
+export declare class ContainerSettingOptions extends DTO {
+    /**
+     * The container name, unique on the Docker host: letters, digits, `_`, `.` and `-`, starting with a letter or a
+     * digit. Docker generates one (`happy_turing`) when absent.
+     */
+    name?: string;
+    /**
+     * The host name seen in the container; Docker uses the first 12 characters of the container ID when absent.
+     */
+    hostname?: string;
+    /**
+     * Run the container privileged (`docker run --privileged`): every capability and every host device, without the
+     * security restrictions. It gives the container full access to the host.
+     */
+    privileged?: boolean;
+    /**
+     * Give the container's main process a terminal (`docker run -t`): its output is then not multiplexed, and
+     * `DockerContainer.logs()` gives it as written.
+     */
+    tty?: boolean;
+    /**
+     * The environment variables, by name (`{NODE_ENV: 'production'}`), added to the image's ones; the values are
+     * strings.
+     */
+    env?: Record<string, string>;
+    /**
+     * The memory limit, in bytes (`256 * 1024 * 1024` for 256 MiB); Docker requires at least 6 MiB. `0` or absent for
+     * no limit. The swap limit is Docker's default: as much swap as memory.
+     * @default 0
+     */
+    memoryLimit?: number;
+    /**
+     * The indexes of the host CPUs the container may run on (`[0, 1]`, sent to Docker as `"0,1"`); all of them when
+     * absent. Each one is an integer.
+     */
+    cpuSet?: number[];
+    /**
+     * When Docker restarts the container after it exits: `''`, `'no'`, `'always'`, `'unless-stopped'`,
+     * `'on-failure'` (with no limit on the retries) or `'on-failure:N'` (`N` retries at most, `'on-failure:3'`); another
+     * value fails the validation. `''` or absent for no restart.
+     */
+    restartPolicy?: ContainerRestartPolicy;
+    /**
+     * The container ports published on the host (`docker run -p`), each one required to have a `port` (a valid port
+     * number) and a `type` (`'tcp'` or `'udp'`), sent to Docker as `"80/tcp"`. Its `hostPorts` are the host ports
+     * forwarded to it, bound on every host address (`[8080]`, each one once); empty, or absent, it is published on no
+     * host port.
+     */
+    ports?: (Pick<ContainerPort, 'port' | 'type'> & Partial<Pick<ContainerPort, 'hostPorts'>>)[];
+    /**
+     * The host files and directories mounted into the container (`docker run -v`), each one required to have its
+     * `hostPath`, its `containerPath` and `rw` (`false` for read-only); sent to Docker as
+     * `"hostPath:containerPath:rw"` or `"hostPath:containerPath:ro"`.
+     */
+    binds?: ContainerBind[];
+    /**
+     * The host devices made available in the container (`docker run --device`), each one required to have its
+     * `hostPath` and its `containerPath`; its `cgroupPermissions`, a combination of `r`, `w` and `m`, is `'rwm'` by
+     * default.
+     */
+    devices?: (Pick<ContainerDevice, 'hostPath' | 'containerPath'> & Partial<Pick<ContainerDevice, 'cgroupPermissions'>>)[];
+    /**
+     * The networks the container is connected to, each one required to have its `networkName`; the default `bridge`
+     * network when absent. On a user-defined network, `ip` (an IPv4 address) and `ipv6` (an IPv6 address) set the
+     * container's static addresses, within the network's range; empty or absent, Docker allocates them. They are
+     * ignored on `bridge`, `host` and `none`.
+     */
+    networks?: (Pick<ContainerNetwork, 'networkName'> & Partial<Pick<ContainerNetwork, 'ip' | 'ipv6'>>)[];
+    /**
+     * Keep the kernel's OOM killer from killing the container's processes when it runs out of memory; set it with a
+     * memory limit only, or the host may kill its own processes instead.
+     */
+    OOMKillDisable?: boolean;
+    /**
+     * The Linux capabilities added to Docker's default set (`docker run --cap-add`); a value outside
+     * {@link ContainerCapability} fails the validation. None added when absent (`update()` keeps the container's).
+     */
+    capabilities?: ContainerCapability[];
+    /**
+     * The cgroup the container runs in (the Docker Engine's `HostConfig.Cgroup`): `'container:<name|id>'` shares
+     * another container's cgroup; its own when absent.
+     */
+    cgroup?: string;
+    /**
+     * The parent cgroup the container's cgroup is created under (`docker run --cgroup-parent`); a relative path is
+     * relative to the cgroup of the init process. The cgroups are created when missing.
+     */
+    cgroupParent?: string;
+    /**
+     * The PID namespace of the container (`docker run --pid`): `'container:<name|id>'` joins another container's,
+     * `'host'` uses the host's; its own when absent.
+     */
+    pidMode?: string;
+    /**
+     * The command, replacing the image's `CMD`: the executable followed by its arguments (`['node', 'server.js']`), an
+     * array only.
+     */
+    cmd?: string[];
+    /**
+     * The entry point, replacing the image's `ENTRYPOINT`: the executable followed by its arguments, an array only.
+     * `['']` removes the image's entry point: the command runs alone.
+     */
+    entrypoint?: string[];
+}

package/dist/cjs/docker/options/container/ContainerSettingOptions.js

@@ -0,0 +1,136 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContainerSettingOptions = void 0;
+const core_1 = require("@lakutata/core");
+const dto_1 = require("@lakutata/core/decorator/dto");
+const ContainerCapability_js_1 = require("../../types/ContainerCapability.js");
+/**
+ * The settings of a container: given to {@link Docker.createContainer} and `DockerImage.run()` (create, then start),
+ * which use the image's defaults (command, environment…) for the settings absent, and to `DockerContainer.update()`,
+ * which changes the settings given and keeps the others: the limits and the restart policy live, the others by
+ * recreating the container. Every option is optional.
+ * @example
+ * ```typescript
+ * import {Docker, ContainerCapability} from 'lakutata/com/docker'
+ *
+ * declare const docker: Docker
+ *
+ * const image = await docker.pullImage({repo: 'nginx', tag: '1.27'})
+ * const container = await image.run({
+ *     name: 'web',
+ *     env: {TZ: 'UTC'},
+ *     memoryLimit: 256 * 1024 * 1024,
+ *     restartPolicy: 'unless-stopped',
+ *     ports: [{port: 80, type: 'tcp', hostPorts: [8080]}],
+ *     binds: [{hostPath: '/srv/web/html', containerPath: '/usr/share/nginx/html', rw: false}],
+ *     networks: [{networkName: 'front'}],
+ *     capabilities: [ContainerCapability.NET_ADMIN]
+ * })
+ * //The same container, with 512 MiB of memory, restarted 3 times at most when it fails
+ * await container.update({memoryLimit: 512 * 1024 * 1024, restartPolicy: 'on-failure:3'})
+ * ```
+ */
+class ContainerSettingOptions extends core_1.DTO {
+}
+exports.ContainerSettingOptions = ContainerSettingOptions;
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.String().optional()),
+    __metadata("design:type", String)
+], ContainerSettingOptions.prototype, "name", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.String().optional()),
+    __metadata("design:type", String)
+], ContainerSettingOptions.prototype, "hostname", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.Boolean().optional()),
+    __metadata("design:type", Boolean)
+], ContainerSettingOptions.prototype, "privileged", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.Boolean().optional()),
+    __metadata("design:type", Boolean)
+], ContainerSettingOptions.prototype, "tty", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.Object().optional()),
+    __metadata("design:type", Object)
+], ContainerSettingOptions.prototype, "env", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.Number().optional()),
+    __metadata("design:type", Number)
+], ContainerSettingOptions.prototype, "memoryLimit", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.Array(core_1.DTO.Number().integer()).optional()),
+    __metadata("design:type", Array)
+], ContainerSettingOptions.prototype, "cpuSet", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.Alternatives(core_1.DTO.String().allow('').valid('', 'no', 'always', 'unless-stopped', 'on-failure'), core_1.DTO.String().pattern(/^on-failure:\d+$/)).optional()),
+    __metadata("design:type", String)
+], ContainerSettingOptions.prototype, "restartPolicy", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.Array(core_1.DTO.Object({
+        port: core_1.DTO.Number().port().required(),
+        type: core_1.DTO.String().valid('tcp', 'udp').required(),
+        hostPorts: core_1.DTO.Array(core_1.DTO.Number().port()).optional().default([])
+    })).optional()),
+    __metadata("design:type", Array)
+], ContainerSettingOptions.prototype, "ports", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.Array(core_1.DTO.Object({
+        hostPath: core_1.DTO.String().required(),
+        containerPath: core_1.DTO.String().required(),
+        rw: core_1.DTO.Boolean().required()
+    })).optional()),
+    __metadata("design:type", Array)
+], ContainerSettingOptions.prototype, "binds", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.Array(core_1.DTO.Object({
+        hostPath: core_1.DTO.String().required(),
+        containerPath: core_1.DTO.String().required(),
+        cgroupPermissions: core_1.DTO.String().optional().default('rwm')
+    })).optional()),
+    __metadata("design:type", Array)
+], ContainerSettingOptions.prototype, "devices", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.Array(core_1.DTO.Object({
+        networkName: core_1.DTO.String().required(),
+        ip: core_1.DTO.String().allow('').ip({ version: 'ipv4' }).optional(),
+        ipv6: core_1.DTO.String().allow('').ip({ version: 'ipv6' }).optional()
+    })).optional()),
+    __metadata("design:type", Array)
+], ContainerSettingOptions.prototype, "networks", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.Boolean().optional()),
+    __metadata("design:type", Boolean)
+], ContainerSettingOptions.prototype, "OOMKillDisable", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.Array(core_1.DTO.String().valid(...Object.values(ContainerCapability_js_1.ContainerCapability))).optional()),
+    __metadata("design:type", Array)
+], ContainerSettingOptions.prototype, "capabilities", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.String().optional()),
+    __metadata("design:type", String)
+], ContainerSettingOptions.prototype, "cgroup", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.String().optional()),
+    __metadata("design:type", String)
+], ContainerSettingOptions.prototype, "cgroupParent", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.String().optional()),
+    __metadata("design:type", String)
+], ContainerSettingOptions.prototype, "pidMode", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.Array(core_1.DTO.String()).optional()),
+    __metadata("design:type", Array)
+], ContainerSettingOptions.prototype, "cmd", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.Array(core_1.DTO.String()).optional()),
+    __metadata("design:type", Array)
+], ContainerSettingOptions.prototype, "entrypoint", void 0);

package/dist/cjs/docker/options/container/ContainerStopOptions.d.ts

@@ -0,0 +1,28 @@
+import { DTO } from '@lakutata/core';
+/**
+ * How `DockerContainer.stop()` and `DockerContainer.restart()` stop a running container (`docker stop`): Docker sends
+ * the stop signal to its main process, then kills it with `SIGKILL` when it has not exited after the timeout.
+ * @example
+ * ```typescript
+ * import {Docker} from 'lakutata/com/docker'
+ *
+ * declare const docker: Docker
+ *
+ * const container = await docker.getContainer('web')
+ * //Up to 30 seconds to finish the requests in progress
+ * await container.stop({signal: 'SIGINT', timeout: 30})
+ * await container.restart({timeout: 5})
+ * ```
+ */
+export declare class ContainerStopOptions extends DTO {
+    /**
+     * The signal sent first, a name (`'SIGINT'`) or a number (`'2'`); the container's stop signal when absent (its
+     * image's `STOPSIGNAL`, `SIGTERM` by default).
+     */
+    signal?: string;
+    /**
+     * The time given to the container to exit before it is killed, in seconds (a whole number); the container's stop
+     * timeout when absent, 10 seconds by default.
+     */
+    timeout?: number;
+}

package/dist/cjs/docker/options/container/ContainerStopOptions.js

@@ -0,0 +1,40 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContainerStopOptions = void 0;
+const core_1 = require("@lakutata/core");
+const dto_1 = require("@lakutata/core/decorator/dto");
+/**
+ * How `DockerContainer.stop()` and `DockerContainer.restart()` stop a running container (`docker stop`): Docker sends
+ * the stop signal to its main process, then kills it with `SIGKILL` when it has not exited after the timeout.
+ * @example
+ * ```typescript
+ * import {Docker} from 'lakutata/com/docker'
+ *
+ * declare const docker: Docker
+ *
+ * const container = await docker.getContainer('web')
+ * //Up to 30 seconds to finish the requests in progress
+ * await container.stop({signal: 'SIGINT', timeout: 30})
+ * await container.restart({timeout: 5})
+ * ```
+ */
+class ContainerStopOptions extends core_1.DTO {
+}
+exports.ContainerStopOptions = ContainerStopOptions;
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.String().optional()),
+    __metadata("design:type", String)
+], ContainerStopOptions.prototype, "signal", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.Number().optional()),
+    __metadata("design:type", Number)
+], ContainerStopOptions.prototype, "timeout", void 0);

package/dist/cjs/docker/options/container/ContainerTTYConsoleSizeOptions.d.ts

@@ -0,0 +1,26 @@
+import { DTO } from '@lakutata/core';
+/**
+ * The size of a container terminal, in characters: its initial size ({@link ContainerCreateTTYOptions.consoleSize}),
+ * and its new size given to `DockerContainerTTY.resize()` when the user's terminal is resized. Both are required.
+ * @example
+ * ```typescript
+ * import {Docker} from 'lakutata/com/docker'
+ *
+ * declare const docker: Docker
+ *
+ * const container = await docker.getContainer('web')
+ * const tty = await container.createTTY({cmd: 'sh', consoleSize: {cols: 120, rows: 40}})
+ * //The user's terminal was resized
+ * await tty.resize({cols: 160, rows: 50})
+ * ```
+ */
+export declare class ContainerTTYConsoleSizeOptions extends DTO {
+    /**
+     * The width, in columns (characters). Required.
+     */
+    cols: number;
+    /**
+     * The height, in rows (lines). Required.
+     */
+    rows: number;
+}

package/dist/cjs/docker/options/container/ContainerTTYConsoleSizeOptions.js

@@ -0,0 +1,40 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContainerTTYConsoleSizeOptions = void 0;
+const core_1 = require("@lakutata/core");
+const dto_1 = require("@lakutata/core/decorator/dto");
+/**
+ * The size of a container terminal, in characters: its initial size ({@link ContainerCreateTTYOptions.consoleSize}),
+ * and its new size given to `DockerContainerTTY.resize()` when the user's terminal is resized. Both are required.
+ * @example
+ * ```typescript
+ * import {Docker} from 'lakutata/com/docker'
+ *
+ * declare const docker: Docker
+ *
+ * const container = await docker.getContainer('web')
+ * const tty = await container.createTTY({cmd: 'sh', consoleSize: {cols: 120, rows: 40}})
+ * //The user's terminal was resized
+ * await tty.resize({cols: 160, rows: 50})
+ * ```
+ */
+class ContainerTTYConsoleSizeOptions extends core_1.DTO {
+}
+exports.ContainerTTYConsoleSizeOptions = ContainerTTYConsoleSizeOptions;
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.Number().required()),
+    __metadata("design:type", Number)
+], ContainerTTYConsoleSizeOptions.prototype, "cols", void 0);
+__decorate([
+    (0, dto_1.Expect)(core_1.DTO.Number().required()),
+    __metadata("design:type", Number)
+], ContainerTTYConsoleSizeOptions.prototype, "rows", void 0);

package/dist/cjs/docker/options/image/ImageBuildOptions.d.ts

@@ -0,0 +1,117 @@
+import { DTO } from '@lakutata/core';
+import type { DockerOutputCallback } from '../../types/DockerOutputCallback.js';
+import { DockerAuthOptions } from '../auth/DockerAuthOptions.js';
+/**
+ * How {@link Docker.buildImage} builds an image with BuildKit (`docker build`), the built image returned. The build
+ * context is the listed files and directories of the working directory, without the ones its `.dockerignore` excludes;
+ * the Dockerfile is always sent. `workdir` and `files` are required.
+ * @example
+ * ```typescript
+ * import {Docker} from 'lakutata/com/docker'
+ *
+ * declare const docker: Docker
+ *
+ * const image = await docker.buildImage({
+ *     workdir: '/srv/projects/api',
+ *     files: ['package.json', 'package-lock.json', 'dist'],
+ *     repoTag: 'api:1.4.0',
+ *     platform: 'linux/amd64',
+ *     buildargs: {NODE_VERSION: '22'},
+ *     outputCallback: (output: Record<string, any>): void => {
+ *         if (output.stream) console.log(output.stream)
+ *     }
+ * })
+ * console.log(image.id)
+ * ```
+ */
+export declare class ImageBuildOptions extends DTO {
+    /**
+     * The directory of the build context on this machine, holding the Dockerfile and its `.dockerignore`. Required.
+     */
+    workdir: string;
+    /**
+     * The files and directories of `workdir` sent as the build context, their paths relative to it (`['package.json',
+     * 'dist']`); the directories are sent with their content, the files excluded by `.dockerignore` are skipped, and
+     * the Dockerfile is added. Required.
+     */
+    files: string[];
+    /**
+     * The path of the Dockerfile in the build context, relative to `workdir`. Ignored when `remote` points to a
+     * Dockerfile.
+     * @default 'Dockerfile'
+     */
+    dockerfile?: string;
+    /**
+     * The repository and tag of the image, `name:tag` (`api:1.4.0`); a name without a tag is tagged `latest`. When
+     * absent, the image is named `unnamed_img_<random hexadecimal>:latest`.
+     */
+    repoTag?: string;
+    /**
+     * The platform of the image, `os[/arch[/variant]]` (`linux/amd64`, `linux/arm64/v8`); `''` for the Docker host's
+     * platform.
+     * @default ''
+     */
+    platform?: string;
+    /**
+     * The stage of a multi-stage Dockerfile to build (`FROM … AS <stage>`); `''` for the last stage.
+     * @default ''
+     */
+    target?: string;
+    /**
+     * A remote build context: a Git repository URL or an HTTP/HTTPS URL. A URL of a text file is used as the
+     * Dockerfile; a URL of a tarball is downloaded by Docker and used as the context, which must then hold the
+     * `dockerfile` path.
+     */
+    remote?: string;
+    /**
+     * Suppress the verbose build output (`docker build --quiet`).
+     * @default false
+     */
+    quiet?: boolean;
+    /**
+     * The former, misspelt name of {@link ImageBuildOptions.quiet}: the build is quiet when either is `true`.
+     * @deprecated Use `quiet`.
+     */
+    quite?: boolean;
+    /**
+     * Build without the build cache (`docker build --no-cache`).
+     * @default false
+     */
+    nocache?: boolean;
+    /**
+     * Remove the intermediate containers after a successful build (the legacy builder's `--rm`; BuildKit creates
+     * none).
+     * @default true
+     */
+    rm?: boolean;
+    /**
+     * Always remove the intermediate containers, even after a failure (the legacy builder's `--force-rm`; BuildKit
+     * creates none).
+     * @default false
+     */
+    forcerm?: boolean;
+    /**
+     * The size of `/dev/shm` in the build containers, in bytes, greater than 0; 64 MiB when absent.
+     */
+    shmsize?: number;
+    /**
+     * The build arguments, by name (`{NODE_VERSION: '22'}`): the values of the Dockerfile's `ARG` instructions, in the
+     * environment of its `RUN` instructions and expanded in its other instructions. They stay visible in the image's
+     * history: not for the secrets.
+     */
+    buildargs?: {
+        [key: string]: string;
+    };
+    /**
+     * The credentials of a private registry the base images come from. When given, the images of the Dockerfile's
+     * `FROM` instructions are pulled first with them (on `platform`, their progress given to `outputCallback`), and
+     * BuildKit is given them (the tokens included) for `auth.serverAddress`.
+     */
+    auth?: DockerAuthOptions;
+    /**
+     * Receive the build progress as it arrives: the BuildKit progress as the lines of `docker build --progress=plain`
+     * (`{id: 'moby.buildkit.trace', stream: '#2 [1/2] FROM alpine'}`), and the other messages of Docker as they are
+     * sent (the built image's ID, `{aux: {ID: 'sha256:…'}}`, the errors, `{error: '…'}`).
+     */
+    outputCallback?: DockerOutputCallback;
+}